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System Information 

and Control 



The system services described in this chapter operate on the system as a whole rather 
than on individual objects within the system. They mostly gather information about 
the performance and operation of the system and set system parameters. 



ZwQuerySystemlnformation 



ZwQuerySystemlnformation queries information about the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySystemlnformation ( 

IN SYSTEM_INFORMATION_CLASS Systemlnf ormationClass , 

IN OUT PVOID Systemlnformation, 

IN ULONG Systemlnf ormationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

Systemlnformation Class 

The type of system information to be queried. The permitted values are a subset of 
the enumeration SYSTEM_INFORMATION_CLASS, described in the following section. 

Systemlnformation 

Points to a caller-allocated buffer or variable that receives the requested system 
information. 

Systemlnf ormationLength 

The size in bytes of Systemlnformation, which the caller should set according to the 
given SystemlnformationClass. 
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ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Systemlnformation; if SystemlnformationLength is too small to contain the available 
information, the variable is normally set to zero except for two information classes 
(6 and 11) when it is set to the number of bytes required for the available information. 
If this information is not needed, ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_INFO_CLASS, 
STATUS_NOT_I IMPLEMENTED or STATUS_INFO_LENGTH MISMATCH. 

Related Win32 Functions 

GetSystemlnfo, GetTimeZonelnf ormation, GetSystemTimeAdj ustment, PSAPI functions, 
and performance counters. 

Remarks 

ZwQuerySystemlnf ormation is the source of much of the information displayed by 
“Performance Monitor” for the classes Cache, Memory, Objects, Paging File, Process, 
Processor, System, and Thread. It is also frequently used by resource kit utilities that 
display information about the system. 

The ReturnLength information is not always valid (depending on the information 
class), even when the routine returns STATUS_SUCCESS. When the return value indicates 
STATUS_INFO_LENGTH_MISMATCH, only some of the information classes return an estimate 
of the required length. 

Some information classes are implemented only in the “checked” version of the 
kernel. Some, such as SystemCallCounts, return useful information only in “checked” 
versions of the kernel. 

Some information classes require certain flags to have been set in NtGlobalFlags at 
boot time. For example, SystemObjectlnformation requires that 
FLG_MAI NTAI N_0B J ECT_TYPE L I ST be set at boot time. 

Information class SystemNot Implement edl (4) would return STATUS_NOT_IMPLEMENTED 
if it were not for the fact that it uses DbgPrint to print the text “EX: 

SystemPathlnf ormation now available via SharedUserData. ” and then calls 
DbgBreakPoint.The breakpoint exception is caught by a frame based exception handler 
(in the absence of intervention by a debugger) and causes ZwQuerySystemlnf ormation 
to return with STATUS_BREAKPOINT. 



ZwSetSystemlnformation 



ZwSetSystemlnformation sets information that affects the operation of the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetSystemlnformation ( 

IN SYSTEM_INFORMATION_CLASS Systemlnf ormationClass , 

IN OUT PVOID Systemlnformation, 
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IN ULONG SystemlnformationLength 

); 



Parameters 

SystemlnformationClass 

The type of system information to be set. The permitted values are a subset of the 
enumeration SYSTEM_INFORMATION_CLASS, described in the following section. 

Systemlnformation 

Points to a caller-allocated buffer or variable that contains the system information to 
be set. 

SystemlnformationLength 

The size in bytes of Systemlnformation, which the caller should set according to the 
given SystemlnformationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_INFO_CLASS, 
STATUS_NOT_I IMPLEMENTED or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

SetSystemTimeAd j ustment. 

Remarks 

At least one of the information classes uses the Systemlnformation parameter for both 
input and output. 



SYSTEM_INFORMATION_CLASS 



The system information classes available in the “free” (retail) build of the system are 
listed below along with a remark as to whether the information class can be queried, 
set, or both. Some of the information classes labeled “SystemNot Implement edXxx” are 
implemented in the “checked” build, and a few of these classes are briefly described 
later. 



typedef enum _SYSTEM_ INFORMATION^ LASS { 

SystemBasicInformation, // 0 

SystemProcessorlnformation, // 1 

SystemPerformancelnformation, // 2 

SystemTimeOfDaylnformation, // 3 

SystemNotlmplementedl , // 4 

SystemProcessesAndThreadsInformation, // 5 

SystemCallCounts , // 6 

SystemConf igurationlnformation, // 7 

SystemProcessorTimes, // 8 

SystemGlobalFlag, // 9 

SystemNotImplemented2, // 10 

SystemModulelnformation, // 11 



Query Set 

Y N 

Y N 

Y N 

Y N 

Y N 

Y N 

Y N 

Y N 

Y N 

Y Y 

Y N 

Y N 
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SystemLocklnf ormation , 


a 


12 


Y 


N 


Sy st emNot Implement ed3, 


a 


13 


Y 


N 


Sy st emNot Implement ed4, 


a 


14 


Y 


N 


Sy st emNot Implement ed5, 


a 


15 


Y 


N 


SystemHandlelnf ormation, 


a 


16 


Y 


N 


SystemObject Inf ormation, 


// 


17 


Y 


N 


SystemPagef ilelnf ormation , 


a 


18 


Y 


N 


SystemlnstructionEmulationCounts, 


a 


19 


Y 


N 


SystemlnvalidlnfoClassI , 


a 


20 






SystemCachelnf ormation , 


a 


21 


Y 


Y 


SystemPoolTaglnf ormation, 


a 


22 


Y 


N 


SystemProcessorStatistics, 


a 


23 


Y 


N 


SystemDpcInf ormation , 


a 


24 


Y 


Y 


Syst emNot Implement ed6, 


a 


25 


Y 


N 


SystemLoadlmage, 


a 


26 


N 


Y 


SystemUnloadlmage, 


a 


27 


N 


Y 


SystemTimeAd j ustment , 


a 


28 


Y 


Y 


Syst emNot Implemented?, 


a 


29 


Y 


N 


Sy st emNot Implement ed8, 


a 


30 


Y 


N 


Sy st emNot Implement ed9, 


a 


31 


Y 


N 


SystemCrashDumpInf ormation , 


a 


32 


Y 


N 


SystemExceptionlnf ormation , 


a 


33 


Y 


N 


SystemCrashDumpStatelnf ormation, 


a 


34 


Y 


Y/N 


SystemKernelDebuggerlnformation, 


a 


35 


Y 


N 


SystemContextSwitchlnf ormation , 


a 


36 


Y 


N 


SystemRegistryQuotalnf ormation, 


a 


37 


Y 


Y 


SystemLoadAndCalllmage , 


// 


38 


N 


Y 


SystemPrioritySeparation , 


a 


39 


N 


Y 


SystemNotlmplementedlO, 


a 


40 


Y 


N 


SystemNotlmplementedl 1 , 


a 


41 


Y 


N 


SystemInvalidInfoClass2, 


a 


42 






SystemInvalidInfoClass3, 


a 


43 






SystemTimeZonelnf ormation , 


a 


44 


Y 


N 


SystemLookasidelnf ormation , 


a 


45 


Y 


N 


SystemSetTimeSlipEvent , 


a 


46 


N 


Y 


SystemCreateSession, 


a 


47 


N 


Y 


SystemDeleteSession, 


a 


48 


N 


Y 


SystemInvalidInfoClass4, 


a 


49 






SystemRangeStart Inf ormation, 


a 


50 


Y 


N 


SystemVerif ierlnf ormation , 


a 


51 


Y 


Y 


SystemAddVerif ier, 


a 


52 


N 


Y 


SystemSessionProcesses Inf ormation 


a 


53 


Y 


N 



} SYSTEM_INFORMATION_CLASS; 



SystemBasicInformation 



typedef struct _S YST E M_B AS I C_I N F 0 RMAT ION { // Information Class 0 
ULONG Unknown; 

ULONG Maximumlncrement ; 

ULONG PhysicalPageSize; 

ULONG NumberOf PhysicalPages; 

ULONG LowestPhysicalPage; 

ULONG HighestPhysicalPage; 

ULONG AllocationGranularity ; 

ULONG LowestUserAddress; 

ULONG HighestUserAddress; 

ULONG ActiveProcessors; 

UCHAR NumberProcessors; 

} SYSTEM_BAS I CONFORMATION, *PSYSTEM_BASIC_INFORMATION; 
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Members 

Unknown 

Always contains zero; interpretation unknown. 

Maximumlncrement 

The maximum number of 100-nanosecond units between clock ticks. Also the 
number of 100-nanosecond units per clock tick for kernel intervals measured in clock 
ticks. 

PhysicalPageSize 

The size in bytes of a physical page. 

Num berOfPhysicalPages 

The number of physical pages managed by the operating system. 

LowestPhysicalPage 

The number of the lowest physical page managed by the operating system (numbered 
from zero). 

Highes tPhysicalPage 

The number of the highest physical page managed by the operating system (numbered 
from zero). 

Allocation Granularity 

The granularity to which the base address of virtual memory reservations is rounded. 

Lowes tUserA ddress 

The lowest virtual address potentially available to user mode applications. 

HighestUser Address 

The highest virtual address potentially available to user mode applications. 

ActiveProcessors 

A bit mask representing the set of active processors in the system. Bit 0 is processor 0; 
bit 31 is processor 31. 

Num berProcessors 

The number of processors in the system. 

Remarks 

Much of the data in this information class can be obtained by calling the Win32 func- 
tion GetSystemlnf o. 
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SystemProeessorlnformation 



typedef struct _SYSTEM_PROCESSOR_INFORMATION { // Information Class 1 
USHORT ProcessorArchitecture; 

USHORT ProcessorLevel; 

USHORT ProcessorRevision; 

USHORT Unknown; 

ULONG FeatureBits; 

} SYSTEM_PROCESSOR_INFORMATION , *PSYSTEM_PROCESSOR_INFORMATION ; 

Members 

Processor A rch itectu re 

The system’s processor architecture. Some of the possible values are defined in winnt.h 
with identifiers of the form PROCESSOR_ARCHITECTURE_* (where ‘*’ is a wildcard). 

ProcessorLevel 

The system’s architecture-dependent processor level. Some of the possible values are 
defined in the Win32 documentation for the SYSTEM_INFO structure. 



ProcessorRevision 

The system’s architecture-dependent processor revision. Some of the possible values are 
defined in the Win32 documentation for the SYSTEM_INFO structure. 



Unknown 

Always contains zero; interpretation unknown. 



FeatureBits 

A bit mask representing any special features of the system’s processor (for example, 
whether the Intel MMX instruction set is available). The flags for the Intel platform 
include: 



Intel Mnemonic 


Value 


VME 


0X0001 


TCS 


0x0002 

0x0004 


CMOV 


0x0008 


PGE 


0x0010 


PSE 


0x0020 


MTRR 


0x0040 


CXS 


0x0080 


MMX 


0x0100 


PAT 


0x0400 


FXSR 


0x0800 


SIMD 


0x2000 



Remarks 



Description 

Virtual-8086 Mode Enhancements 
Time Stamp Counter 
CR4 Register 

Conditional Mov/Cmp Instruction 

PTE Global Bit 

Page Size Extensions 

Memory Type Range Registers 

CMPXCHGB8 Instruction 

MMX Technology 

Page Attribute Table 

Fast Floating Point Save and Restore 

Streaming SIMD Extension 



Much of the data in this information class can be obtained by calling the Win32 
function GetSystemlnfo. 
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SystemPerformancelnformation 



typedef struct _SYSTEM_PERFORMANCE_INFORMATION { // Information Class 2 
LARGE_INTEGER IdleTime; 

LARGE_INTEGER ReadTransf erCount ; 

LARGE_INTEGER WriteT ransf erCount ; 

LARGE_INTEGER OtherT ransf erCount ; 

ULONG ReadOperationCount ; 

ULONG WriteOperationCount ; 

ULONG OtherOperationCount ; 

ULONG AvailablePages; 

ULONG TotalCommittedPages; 

ULONG Tot alCommit Limit ; 

ULONG PeakCommitment ; 

ULONG PageFaults; 

ULONG WriteCopyFaults; 

ULONG TransitionFaults; 

ULONG Reservedl ; 

ULONG DemandZeroFaults; 

ULONG PagesRead; 

ULONG PageReadlos; 

ULONG Reserved2[2] ; 

ULONG PagefilePagesWritten; 

ULONG PagefilePageWritelos; 

ULONG MappedFilePagesWritten; 

ULONG MappedFilePageWritelos; 

ULONG PagedPoolUsage; 

ULONG NonPagedPoolUsage; 

ULONG PagedPoolAllocs; 

ULONG PagedPoolFrees; 

ULONG NonPagedPoolAllocs; 

ULONG NonPagedPoolFrees; 

ULONG TotalFreeSystemPtes; 

ULONG SystemCodePage; 

ULONG TotalSystemDriverPages; 

ULONG TotalSystemCodePages; 

ULONG SmallNonPagedLookasideListAllocateHits ; 

ULONG SmallPagedLookasideListAllocateHits ; 

ULONG Reserved3; 

ULONG MmSystemCachePage; 

ULONG PagedPoolPage; 

ULONG SystemDriverPage; 

ULONG FastReadNoWait; 

ULONG FastReadWait; 

ULONG FastReadResourceMiss; 

ULONG FastReadNotPossible; 

ULONG FastMdlReadNoWait ; 

ULONG FastMdlReadWait ; 

ULONG FastMdlReadResourceMiss; 

ULONG FastMdlReadNotPossible; 

ULONG MapDataNoWait; 

ULONG MapDataWait; 

ULONG MapDataNoWaitMiss; 

ULONG MapDataWaitMiss; 

ULONG PinMappedDataCount ; 

ULONG PinReadNoWait; 

ULONG PinReadWait; 

ULONG PinReadNoWaitMiss; 

ULONG PinReadWaitMiss; 

ULONG CopyReadNoWait; 

ULONG CopyReadWait; 

ULONG CopyReadNoWaitMiss; 
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8 System Information and Control: SystemPerformancelnformation 



ULONG CopyReadWaitMiss; 

ULONG MdlReadNoWait ; 

ULONG MdlReadWait ; 

ULONG MdlReadNoWaitMiss ; 

ULONG MdlReadWaitMiss; 

ULONG ReadAheadlos; 

ULONG LazyWritelos; 

ULONG LazyWritePages; 

ULONG DataFlushes; 

ULONG DataPages; 

ULONG ContextSwitches; 

ULONG FirstLevelTbFills ; 

ULONG SecondLevelTbFills; 

ULONG SystemCalls; 

} SYSTEM_PERFORMANCE_INFORMATION , *PSYSTEM_PERFORMANCE_INFORMATION ; 

Members 



IdleTime 

The total idle time, measured in units of 100-nanoseconds, of all the processors in the 
system. 



ReadTransferCount 

The number of bytes read by all calls to ZwReadFile. 

WriteTransfer Count 

The number of bytes written by all calls to ZwWriteFile. 
OtherTransferCount 

The number of bytes transferred to satisfy all other I/O operations, such as 

ZwDeviceloControlFile. 



Read OperationCount 

The number of calls to ZwReadFile. 

Wri te Opera tion Count 

The number of calls to ZwWriteFile. 

OtherOperationCount 

The number of calls to all other I/O system services such as ZwDeviceloControlFile. 
AvailablePages 

The number of pages of physical memory available to processes running on the 
system. 

Total CommittedPages 

The number of pages of committed virtual memory. 

TotalCommitLimit 

The number of pages of virtual memory that could be committed without 
extending the systems pagefiles. 
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PeakCommitment 

The peak number of pages of committed virtual memory. 

PageFaults 

The number of page faults (both soft and hard). 

WriteCopyFaults 

The number of page faults arising from attempts to write to copy-on- write pages. 

TransitionFaults 

The number of soft page faults (excluding demand zero faults) . 

DemandZeroFaults 

The number of demand zero faults. 

PagesRead 

The number of pages read from disk to resolve page faults. 

PageReadlos 

The number of read operations initiated to resolve page faults. 

Pagefi lePages Written 

The number of pages written to the system’s pagefiles. 

Pagefi I e Page Writelos 

The number of write operations performed on the systems pagefiles. 

MappedFilePages Written 

The number of pages written to mapped files. 

MappedFilePage Writelos 

The number of write operations performed on mapped files. 

PagedPoolUsage 

The number of pages of virtual memory used by the paged pool. 

NonPagedPooIUsage 

The number of pages of virtual memory used by the nonpaged pool. 

PagedPoolAllocs 

The number of allocations made from the paged pool. 

PagedPoolFrees 

The number of allocations returned to the paged pool. 

NonPagedPoolAllocs 

The number of allocations made from the nonpaged pool. 
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NonPagedPoolFrees 

The number of allocations returned to the nonpaged pool. 

To ta IFreeSystemPtes 

The number of available System Page Table Entries. 

System CodePage 

The number of pages of pageable operating system code and static data in physical 
memory. The meaning of “operating system code and static data” is defined by address 
range (lowest system address to start of system cache) and includes a contribution from 
win32k.sys. 

Total SystemDriverPages 

The number of pages of pageable device driver code and static data. 

TotalSystem CodePages 

The number of pages of pageable operating system code and static data. The meaning 
of “operating system code and static data” is defined by load time (SERVICE_B00T_START 
driver or earlier) and does not include a contribution from win32k.sys. 

SmallNonPagedLookasideListAllocateHits 

The number of times an allocation could be satisfied by one of the small nonpaged 
lookaside lists. 

SmallPagedLookasideListAllocateHits 

The number of times an allocation could be satisfied by one of the small-paged 
lookaside lists. 

Mm System CachePage 

The number of pages of the system cache in physical memory. 

PagedPoolPage 

The number of pages of paged pool in physical memory. 

SystemDriverPage 

The number of pages of pageable device driver code and static data in physical 
memory. 

FastReadNo Wait 

The number of asynchronous fast read operations. 

FastReadWait 

The number of synchronous fast read operations. 

FastReadResourceMiss 

The number of fast read operations not possible because of resource conflicts. 
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11 



FastReadNotPossible 

The number of fast read operations not possible because file system intervention 
required. 

FastMdlReadNo Wait 

The number of asynchronous fast read operations requesting a Memory Descriptor 
List (MDL) for the data. 

FastMdlRead Wait 

The number of synchronous fast read operations requesting an MDL for the data. 

FastMdlReadResourceMiss 

The number of synchronous fast read operations requesting an MDL for the data not 
possible because of resource conflicts. 

FastMdlReadNotPossible 

The number of synchronous fast read operations requesting an MDL for the data not 
possible because file system intervention required. 

MapDataNo Wait 

The number of asynchronous data map operations. 

MapDataWait 

The number of synchronous data map operations. 

MapDataNo WaitMiss 

The number of asynchronous data map operations that incurred page faults. 

MapData WaitMiss 

The number of synchronous data map operations that incurred page faults. 

PinMappedData Count 

The number of requests to pin mapped data. 

PinReadNo Wait 

The number of asynchronous requests to pin mapped data. 

PinReadWait 

The number of synchronous requests to pin mapped data. 

PinReadNo WaitMiss 

The number of asynchronous requests to pin mapped data that incurred page faults 
when pinning the data. 

PinRead WaitMiss 

The number of synchronous requests to pin mapped data that incurred page faults 
when pinning the data. 
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CopyReadNo Wait 

The number of asynchronous copy read operations. 

Copy Read Wait 

The number of synchronous copy read operations. 

CopyReadNo WaitMiss 

The number of asynchronous copy read operations that incurred page faults when 
reading from the cache. 

Copy Read WaitMiss 

The number of synchronous copy read operations that incurred page faults when 
reading from the cache. 

MdlReadNo Wait 

The number of synchronous read operations requesting an MDL for the cached data. 

MdlReadWait 

The number of synchronous read operations requesting an MDL for the cached data. 

MdlReadNo WaitMiss 

The number of synchronous read operations requesting an MDL for the cached data 
that incurred page faults. 

MdlRead WaitMiss 

The number of synchronous read operations requesting an MDL for the cached data 
that incurred page faults. 

ReadAheadlos 

The number of read ahead operations performed in anticipation of sequential access. 

Lazy Writelos 

The number of write operations initiated by the Lazy Writer. 

Lazy WritePages 

The number of pages written by the Lazy Writer. 

DataFlushes 

The number of cache flushes in response to flush requests. 

DataPages 

The number of cache pages flushed in response to flush requests. 

ContextSwitch.es 

The number of context switches. 

Firs t Level Tb Fills 

The number of first level translation buffer fills. 



1996 CHOI 11/19/99 12:24 PM Page 13 



System Information and Control: SystemProcessesAndThreadsInformation 13 

SecondLevelTbFills 

The number of second level translation buffer fills. 

System Calls 

The number of system calls executed. 

Remarks 

Slightly longer descriptions of many of the members of this structure can be found in 
the Win32 documentation for the NT Performance Counters. 



SystemTimeOfDaylnformation 



typedef struct _SYSTEM_TIME_OF_DAY_INFORMATION { // Information Class 3 
LARGE_INTEGER BootTime; 

LARGE_INTEGER CurrentTime; 

LARGE_INTEGER TimeZoneBias ; 

ULONG CurrentTimeZoneld; 

} SYSTEM_TIME_OF_DAY_INFORMATION, *PSYSTEM_TIME_OF_DAY_INFORMATION; 

Members 

BootTime 

The time when the system was booted in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

CurrentTime 

The current time of day in the standard time format. 

TimeZoneBias 

The difference, in 100-nanosecond units, between Coordinated Universal Time (UTC) 
and local time. 

CurrentTimeZoneld 

A numeric identifier for the current time zone. 



Remarks 

None. 



SystemProcessesAndThreadsInformation 



typedef struct _SYSTEM_PROCESSES { // Information Class 5 
ULONG NextEntryDelta; 

ULONG ThreadCount; 

ULONG Reservedl [6] ; 

LARGE_INTEGER CreateTime; 

LARGE_INTEGER UserTime; 

LARGE_INTEGER KernelTime; 

UNICODE_STRING ProcessName; 

KPRIORITY BasePriority ; 

ULONG Processld; 
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ULONG InheritedFromProcessId; 

ULONG HandleCount; 

ULONG Reserved2[2] ; 

VM_COUNTERS VmCounters; 

I0_C0UNTERS IoCounters; // Windows 2000 only 
SYSTEM_THREADS Threads [ 1 ] ; 

} SYSTEM_PROCESSES , *PSYSTEM_PROCESSES; 

typedef struct _SYSTEM_THREADS { 

LARGE_INTEGER KernelTime; 

LARGE_INTEGER UserTime; 

LARGE_INTEGER CreateTime; 

ULONG WaitTime; 

PVOID StartAddress; 

CLIENT_ID Clientld; 

KPRIORITY Priority; 

KPRIORITY BasePriority ; 

ULONG ContextSwitchCount ; 

THREAD_STATE State; 

KWAIT_REASON WaitReason; 

} SYSTEM_THREADS , *PSYSTEM_THREADS; 

Members 



NextEntryDelta 

The offset, from the start of this structure, to the next entry. A NextEntryDelta of zero 
indicates that this is the last structure in the returned data. 



ThreadCount 

The number of threads in the process. 



CreateTime 

The creation time of the process in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 



UserTime 

The sum of the time spent executing in user mode by the threads of the process, 
measured in units of 100-nanoseconds. 



KernelTime 

The sum of the time spent executing in kernel mode by the threads of the process, 
measured in units of 100-nanoseconds. 



ProcessName 

The name of the process, normally derived from the name of the executable file used 
to create the process. 

BasePriority 

The default base priority for the threads of the process. 

Processld 

The process identifier of the process. 
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InheritedFromProcessId 

The process id of the process from which handles and/ or address space was inherited. 

HandleCount 

The number of handles opened by the process. 

VmCounters 

Statistics on the virtual memory usage of the process. VM_COUNTERS is defined thus in 
ntddk.h: 



typedef struct _VM_COUNTERS { 

ULONG PeakVirtualSize; 

ULONG VirtualSize; 

ULONG PageFaultCount; 

ULONG PeakWorkingSetSize; 

ULONG WorkingSetSize; 

ULONG QuotaPeakPagedPoolUsage; 
ULONG QuotaPagedPoolUsage; 

ULONG QuotaPeakNonPagedPoolUsage ; 
ULONG QuotaNonPagedPoolUsage; 
ULONG Pagef ileUsage; 

ULONG PeakPagef ileUsage; 

} VM_COUNTERS, *PVM_COUNTERS; 



Io Counters 

Statistics on the I/O operations of the process. This information is only present in 
Windows 2000. I0_C0UNTERS is defined thus: 

typedef struct _I0_C0UNTERS { 

LARGE_INTEGER ReadOperationCount ; 

LARGE_INTEGER WriteOperationCount ; 

LARGE_INTEGER OtherOperationCount ; 

LARGE_INTEGER ReadTransf erCount ; 

LARGE_INTEGER WriteT ransf erCount ; 

LARGE_INTEGER OtherT ransf erCount ; 

} I0_C0UNTERS, *PI0_C0UNTERS; 



Threads 

An array of SYSTEM_THREADS structures describing the threads of the process. The num- 
ber of elements in the array is available in the ThreadCount member. 

The members of SYSTEM_THREADS aredescribed in the following secctions. 

KernelTime 

The time spent executing in kernel mode, measured in units of 100-nanoseconds. 

UserTime 

The time spent executing in user mode, measured in units of 100-nanoseconds. 

CreateTime 

The creation time of the thread in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 
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WaitTime 

The time at which the thread last entered a wait state, measured in clock ticks since 

system boot. 

StartAddress 

The start address of the thread. 

Clientld 

The client identifier of the thread, comprising a process identifier and a thread 

identifier. 

Priority 

The priority of the thread. 

BasePriority 

The base priority of the thread. 

ContextSwitchCount 

The number of context switches incurred by the thread. 

State 

The execution state of the thread. Permitted values are drawn from the enumeration 

THREAD_STATE. 

typedef enum { 

Statelnitialized, 

StateReady, 

StateRunning, 

StateStandby, 

StateTerminated, 

StateWait , 

StateTransition, 

Statellnknown 
} THREAD_STATE ; 



WaitReason 

An indication of the reason for a wait. Some possible values are defined in the 
enumeration KWAIT_REASON, but other values may also be used. 

typedef enum _KWAIT_REASON { 

Executive, 

FreePage, 

Pagein, 

PoolAllocation, 

DelayExecution, 

Suspended, 

UserRequest, 

WrExecutive, 

WrFreePage, 

WrPageln, 

WrPoolAllocation , 

WrDelayExecution , 

WrSuspended, 

WrUserRequest , 

WrEventPair, 
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WrQueue, 

WrLpcReceive, 

WrLpcReply , 

WrVirtualMemory , 

WrPageOut , 

WrRendezvous, 

Spare2, 

Spare3, 

Spare4, 

Spare5, 

Spare6, 

WrKernel 
} KWAIT_R EASON; 

Remarks 

The format of the data returned to the Systemlnformation buffer is a sequence of 
SYSTEM_PROCESSES structures, chained together via the NextEntryDelta member. 

The Threads member of each SYSTEM_PROCESSES structure is an array of ThreadCount 
SYSTEM_THREADS structures. The end of the process chain is marked by a NextEntryDelta 
value of zero. 

The Process Status API (PSAPI) function EnumProcesses uses this information class to 
obtain a list of the process identifier in the system. 

An demonstration of the use of this information class to implement a subset of the 
Tool Help Library appears in Example 1.1. 

The addition of the IoCounters member to SYSTEM_PROCESSES structure in Windows 
2000 has the consequence that Windows NT 4.0 applications that access the Threads 
member fail when run under Windows 2000; for example the pstat.exe resource kit 
utility suffers from this problem. 



SystemCallCounts 



typedef struct _SYSTEM_CALLS_INF0RMATI0N { // Information Class 6 
UL0NG Size; 

UL0NG NumberOfDescriptorTables; 

UL0NG Number0fRoutinesInTable[1 ] ; 

// UL0NG CallCountsM; 

} SYSTEM_CALLS_INF0RMATI0N , *PSYSTEM_CALLS_INF0RMATI0N; 

Members 

Size 

The size in bytes of the returned information. 

NumberOfDescriptorTables 

The number of system service dispatch descriptor tables for which information is 
available. 

NumberOfRoutinesInTable 

An array of the count of routines in each table. 
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Remarks 

Information on the number of calls to each system service is only gathered if the 
“checked” version of the kernel is used and memory is allocated by the creator of the 
table to hold the counts. 

The counts of calls to each system service follow the array NumberOfRoutinesInTable. 



SystemConfigurationlnformation 



typedef struct _SYSTEM_CONFIGURATION_INFORMATION { // Information Class 7 
ULONG DiskCount; 

ULONG FloppyCount; 

ULONG CdRomCount; 

ULONG TapeCount; 

ULONG SerialCount; 

ULONG ParallelCount ; 

} SYSTEM_CONFIGURATION_INFORMATION, *PSYSTEM_CONFIGURATION_INFORMATION; 

Members 

DiskCount 

The number of hard disk drives in the system. 

FloppyCount 

The number of floppy disk drives in the system. 

CdRomCount 

The number of CD-ROM drives in the system. 

TapeCount 

The number of tape drives in the system. 

SerialCount 

The number of serial ports in the system. 

ParallelCount 

The number of parallel ports in the system. 

Remarks 

This information is a subset of the information available to device drivers by calling 
IoGetConf igu rat ion Informat ion. 



SystemProcessorTimes 



typedef struct _SYSTEM_PROCESSOR_T I MES { // information Class 8 
LARGE_INTEGER IdleTime; 

LARGE_INTEGER KernelTime; 

LARGE_INTEGER UserTime; 

LARGE_INTEGER DpcTime; 







1996 CHOI 11/19/99 12:24 PM Page 19 



System Information and Control: SystemGlobalFlag 



19 



LARGE_INTEGER InterruptTime ; 

ULONG InterruptCount ; 

} SYSTEM_PROCESSOR_TIMES , *PSYSTEM_PROCESSOR_TIMES; 

Members 

IdleTime 

The idle time, measured in units of 100-nanoseconds, of the processor. 

KernelTime 

The time the processor spent executing in kernel mode, measured in units of 100- 
nanoseconds. 

UserTime 

The time the processor spent executing in user mode, measured in units of 100- 
nanoseconds. 

DpcTime 

The time the processor spent executing deferred procedure calls, measured in units of 
100-nanoseconds. 

InterruptTime 

The time the processor spent executing interrupt routines, measured in units of 100- 
nanoseconds. 

InterruptCount 

The number of interrupts serviced by the processor. 

Remarks 

An array of structures is returned, one per processor. 



SystemGlobalFlag 



typedef struct _SYSTEM_GLOBAL_FLAG { // Information Class 9 
ULONG GlobalFlag; 

} SYSTEM_GLOBAL_FLAG , *PSYSTEM_GLOBAL_FLAG; 

Members 

GlobalFlag 

A bit array of flags that control various aspects of the behavior of the kernel. 

Remarks 

This information class can be both queried and set. SeDebugPrivilege is required to set 
the flags. Some flags are used only at boot time and subsequent changes have no effect. 
Some flags have an effect only when using a “checked” kernel. 
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The flags recognized by the “gflags” resource kit utility are: 



FLG_ST0P_0N_EXCEPTI0N 

FLG_SHOW_LDR_SNAPS 

FLG_DEBUG_I NITIAL_COMMAND 

FLG_ST0P_0N_HUNG_GUI 

F LG_H E AP_E N AB L E_T A I L_C HECK 

FLG_HEAP_ENABLE_FREE_CHECK 

FLG_H EAP_VAL I D AT E_P AR AM ET E R S 

FLG_H EAP_VAL I DAT E_AL L 

FLG_POOL_ENABLE_TAIL_CHECK 

FLG_POOL_ENABLE_FREE_CHECK 

FLG_P00L_ENABLE_TAGGING 

F LG_H EAP_E NAB L E_T AGG I NG 

FLG_USER_STACK_TRACE_DB 

FLG_KERNEL_STACK_TRACE_DB 

FLG_MAI NTAI N_0B J ECT_TYPE L I ST 

F LG_H E AP_E N AB L E_TAG_BY_D L L 

FLG_IGNORE_DEBUG_PRIV 

FLG_ENABLE_CSRDEBUG 

FLG_ENABLE_KDEBUG_SYMBOL_LOAD 

F LG_D I SAB L E_PAG E_KERNE L_STACKS 

FLG_HEAP_ENABLE_CALL_TRACING 

FLG_HEAP_DISABLE_COALESCING 

FLG_ENABLE_CLOSE_EXCEPTIONS 

FLG_ENABLE_EXCEPT I 0N_L0GG I NG 

FLG_ENABLE_DBGPRINT_BUFFERING 



0x00000001 

0x00000002 

0x00000004 

0x00000008 

0x00000010 

0x00000020 

0x00000040 

0x00000080 

0x00000100 

0x00000200 

0x00000400 

0x00000800 

0x00001000 

0x00002000 

0X00004000 

0x00008000 

0x00010000 

0x00020000 

0x00040000 

0x00080000 

0x00100000 

0x00200000 

0x00400000 

0x00800000 

0x08000000 



SystemModulelnformation 



typedef struct _SYSTEM_MODULE_INFORMATION { // Information Class 11 
ULONG Reserved [2]; 

PVOID Base; 

ULONG Size; 

ULONG Flags; 

USHORT Index; 

USHORT Unknown; 

USHORT LoadCount; 

USHORT ModuleNameOff set ; 

CHAR ImageName[256] ; 

} SYSTEM_MODULE_INFORMATION , *PSYSTEM_MODULE_INFORMATION ; 

Members 

Base 

The base address of the module. 



Size 

The size ol the module. 

Flags 

A bit array of flags describing the state of the module. 

Index 

The index of the module in the array of modules. 
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Unknown 

Normally contains zero; interpretation unknown. 

LoadCount 

The number of references to the module. 

ModuleNameOffset 

The offset to the final filename component of the image name. 

ImageName 

The filepath of the module. 



Remarks 

The data returned to the Systemlnformation buffer is a ULONG count of the number of 
modules followed immediately by an array of SYSTEM_MODULE_INFORMATION. 

The system modules are the Portable Executable (PE) format files loaded into the 
kernel address space (ntoskrnl.exe, hal.dll, device drivers, and so on) and ntdll.dll. 

The PSAPI function EnumDeviceDrivers uses this information class to obtain a list of 
the device drivers in the system. It is also used by the PSAPI functions 
GetDeviceDriverFileName and GetDeviceDriverBaseName. 

The code in Example 1.3 uses this information class. 



SystemLocklnformation 



typedef struct _SYSTEM_LOCK_INFORMATION { // Information Class 12 
PVOID Address; 

USHORT Type; 

USHORT Reservedl ; 

ULONG ExclusiveOwnerThreadld; 

ULONG ActiveCount; 

ULONG ContentionCount ; 

ULONG Reserved2[2] ; 

ULONG NumberOfSharedWaiters; 

ULONG NumberOf ExclusiveWaiters; 

} SYSTEM_LOCK_INFORMATION , *PSYSTEM_LOCK_INFORMATION ; 

Members 

Address 

The address of the ERESOURCE structure. 

Type 

The type of the lock. This is always RTL_RESOURCE_TYPE (1 ). 

ExclusiveOwnerThreadld 

The thread ID of the owner of the resource if the resource is owned exclusively, oth- 



erwise zero. 
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ActiveCount 

The number of threads granted access to the resource. 

ContentionCount 

The number of times a thread had to wait for the resource. 

NumberOfShared Waiters 

The number of threads waiting for shared access to the resource. 

NumberOfExclusive Waiters 

The number of threads waiting for exclusive access to the resource. 



Remarks 

The data returned to the Systemlnf ormation buffer is a ULONG count of the number of 
locks followed immediately by an array of SYSTEM_LOCK_INFORMATION. 

The locks reported on by this information class are only available to kernel mode 
code. The locks support multiple reader single writer functionality and are known as 
“resources.” They are initialized by the routine ExInitializeResourceLite and are doc- 
umented in the DDK. 



SystemHandlelnformation 



typedef struct _SYSTEM_HANDLE_INFORMATION { // Information Class 16 
ULONG Processld; 

UCHAR ObjectTypeNumber; 

UCHAR Flags; // 0x01 = PR0TECT_FR0M_CL0SE, 0x02 = INHERIT 
USHORT Handle; 

PVOID Object; 

ACCESS_MASK GrantedAccess ; 

} SYSTEM_HANDLE_INFORMATION , *PSYSTEM_HANDLE_INFORMATION ; 

Members 

Processld 

The process identifier of the owner of the handle. 

ObjectTypeNumber 

A number which identifies the type of object to which the handle refers. The number 
can be translated to a name by using the information returned by ZwQueryObject. 

Flags 

A bit array of flags that specify properties of the handle. 

Handle 

The numeric value of the handle. 

Object 

The address of the kernel object to which the handle refers. 
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GrantedAccess 

The access to the object granted when the handle was created. 

Remarks 

The data returned to the Systemlnf ormation buffer is a ULONG count of the number of 
handles followed immediately by an array of SYSTEM_HANDLE_INFORMATION. 

Examples of the use of this information class to implement utilities that list the open 
handles of processes appear in Example 1.2 and Example 2.1 in Chapter 2, “Object 
Directories, and Symbolic Links.” 



SystemObjectlnformation 



typedef struct _SYSTEM_OBJECT_TYPE_INFORMATION { // Information Class 17 
ULONG NextEntryOff set ; 

ULONG ObjectCount; 

ULONG HandleCount; 

ULONG TypeNumber; 

ULONG InvalidAttributes; 

GENERIC_MAPPING GenericMapping ; 

ACCESS_MASK ValidAccessMask; 

P00L_TYPE PoolType; 

UCHAR Unknown; 

UNICODE_STRING Name; 

} SYSTEM_OBJ ECT_TYPE_I N FORMATI ON , * PS YSTEM_0B J ECT_TYPE_IN FORMATION ; 

typedef struct _SYSTEM_OBJECT_INFORMATION { 

ULONG NextEntryOff set ; 

PVOID Object; 

ULONG CreatorProcessId; 

USHORT Unknown; 

USHORT Flags; 

ULONG PointerCount ; 

ULONG HandleCount; 

ULONG PagedPoolUsage; 

ULONG NonPagedPoolUsage; 

ULONG ExclusiveProcessId; 

PSECURITY_DESCRIPTOR SecurityDescriptor ; 

UNI C0DE_STR I NG Name; 

} SYSTEM_OBJECT_INFORMATION, *PSYSTEM_OBJECT_INFORMATION ; 

Members 

NextEntry Offset 

The offset from the start of the Systemlnf ormation buffer to the next entry. 

ObjectCount 

The number of objects of this type in the system. 

HandleCount 

The number of handles to objects of this type in the system. 

TypeNumber 

A number that identifies this object type. 
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Invalid Attributes 

A bit mask of the 0BJ_Xxx attributes that are not valid for objects of this type. The 
defined attributes are: 

OBJ_INHERIT 

OBJ_PERMANENT 

OBJ_EXCLUSIVE 

OBJ_CASE_INSENSITIVE 

0BJ_0PENIF 

0BJ_0PENLINK 

OBJ_KERNEL_HANDLE // Windows 2000 only 

GenericMapping 

The mapping of generic access rights to specific access rights for this object type. 

ValidAccessMask 

The valid specific access rights for this object type. 

PoolType 

The type of pool from which this object type is allocated (paged or nonpaged). 

Unknown 

Interpretation unknown. 

Name 

A name that identifies this object type. 

The members of SYSTEM_OBJECT_INFORMATION are described in the following sections. 

NextEn try Offset 

The offset from the start of the Systemlnf ormation buffer to the next entry. 

Object 

The address of the object. 

Crea to r Process Id 

The process identifier of the creator of the object. 

Unknown 

Normally contains zero; interpretation unknown. 

Flags 

A bit array of flags that specify properties of the object. Observed values include: 



SINGLE_HANDLE_ENTRY 

DEFAULT_SECURITY_QUOTA 

PERMANENT 

EXCLUSIVE 

CREAT0R_INF0 

KERNEL_MODE 



0x40 

0x20 

0x10 

0x08 

0x04 

0x02 



PointerCount 

The number of pointer references to the object. 
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HandleCount 

The number of handle references to the object. 

Page dPoolUs age 

The amount of paged pool used by the object. 

NonPagedPoolUsage 

The amount of nonpaged pool used by the object. 

ExclusiveProcessId 

The process identifier of the owner of the object if it was created for exclusive use 
(by specifying OBJ_EXCLUSIVE). 

Secu ri ty Descrip to r 

The security descriptor for the object. 



Name 

The name of the object. 



Remarks 



This information class is only available if FLG_MAINTAIN_OBJECT_TYPELIST was set in 
NtGlobalFlags at boot time. 



The format of the data returned to the Systemlnf ormation buffer is a sequence of 
SYSTEM_OBJECT_TYPE_INFORMATION structures, chained together via the NextEntryOff set 
member. Immediately following the name of the object type is a sequence of 
SYSTEM_OBJECT_INFORMATION structures, which are chained together via the 
NextEntryOff set member. The ends of both the object type chain and the object chain 
are marked by a NextEntryOff set value of zero. 



The use of this information class to implement a utility that fists the open handles of 
processes appears in Example 1.2. 



SystemPagefilelnformation 



typedef struct _SYSTEM_PAGEFILE_INFORMATION { // Information Class 18 
ULONG NextEntryOff set ; 

ULONG CurrentSize; 

ULONG TotalUsed; 

ULONG PeakUsed; 

UNICODE_STRING FileName; 

} SYSTEM_PAGEFILE_INFORMATION, *PSYSTEM_PAGEFILE_INFORMATION ; 

Members 

NextEntry Offset 

The offset from the start of the Systemlnf ormation buffer to the next entry. 

CurrentSize 

The current size in pages of the page file. 
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TotalUsed 

The number of pages in the page file that are in use. 

PeakUsed 

The peak number of pages in the page file that have been in use. 

FileName 

The filepath of the page file. 

Remarks 

None. 



SystemlnstructionEmulationCounts 

typedef struct _SYSTEM_INSTRUCTION_EMULATION_INFORMATION { // Info Class 19 
ULONG SegmentNotPresent ; 

ULONG TwoByteOpcode; 

ULONG ESprefix; 

ULONG CSprefix; 

ULONG SSprefix; 

ULONG DSprefix; 

ULONG FSPrefix; 

ULONG GSprefix; 

ULONG 0PER32pref ix; 

ULONG ADDR32pref ix; 

ULONG INSB; 

ULONG I NSW; 

ULONG OUTSB; 

ULONG OUTSW; 

ULONG PUSHFD; 

ULONG POPFD; 

ULONG INTnn; 

ULONG INTO; 

ULONG IRETD; 

ULONG INBimm; 

ULONG INWimm; 

ULONG OUTBimm; 

ULONG OUTWimm; 

ULONG INB; 

ULONG INW; 

ULONG OUTB; 

ULONG OUTW; 

ULONG LOCKprefix; 

ULONG REPNEprefix; 

ULONG REPprefix; 

ULONG HLT ; 

ULONG CLI; 

ULONG STI; 

ULONG GenericInvalidOpcode; 

} SYSTEM_INSTRUCTION_EMULATION_INFORMATION , 
*PSYSTEM_INSTRUCTION_EMULATION_INFORMATION; 

Remarks 

The members of this structure are the number of times that particular instructions had 
to be emulated for virtual DOS machines. The prefix opcodes do not themselves 
require emulation, but they may prefix an opcode that does require emulation. 
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SystemCachelnformation 



typedef struct _SYSTEM_CACHE_INFORMATION { // Information Class 21 
ULONG SystemCacheWsSize; 

ULONG SystemCacheWsPeakSize; 

ULONG SystemCacheWsFaults; 

ULONG SystemCacheWsMinimum; 

ULONG SystemCacheWsMaximum; 

ULONG TransitionSharedPages; 

ULONG TransitionSharedPagesPeak; 

ULONG Reserved [2]; 

} SYSTEM_CACHE_INFORMATION , *PSYSTEM_CACHE_INFORMATION ; 

Members 

System Cache WsSize 

The size in bytes of the system working set. 

System Cache WsPeakSize 

The peak size in bytes of the system working set. 

System Cache WsFaults 

The number of page faults incurred by the system working set. 

System Cache Ws Minimum 

The minimum desirable size in pages of the system working set. 

System Cache WsMaximum 

The maximum desirable size in pages of the system working set. 

TransitionSharedPages 

The sum of the number of pages in the system working set and the number of shared 
pages on the Standby list. This value is only valid in Windows 2000. 

TransitionSharedPagesPeak 

The peak number of shared pages on the Standby list. This value is only valid in 
Windows 2000. 



Remarks 

This information class can be both queried and set. When setting, only the 
SystemCacheWsMinimum and SystemCacheWsMaximum values are used. 



SystemPoolTaglnformation 



typedef struct _SYSTEM_P00L_TAG_INF0RMATI0N { // Information Class 22 
CHAR Tag [4]; 

ULONG PagedPoolAllocs; 

ULONG PagedPoolFrees; 

ULONG PagedPoolUsage; 

ULONG NonPagedPoolAllocs; 
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ULONG NonPagedPoolFrees; 

ULONG NonPagedPoolUsage; 

} SYSTEM_POOL_TAG_INFORMATION , *PSYSTEM_POOL_TAG_INFORMATION ; 

Members 

Tag 

The four character tag string identifying the contents of the pool allocation. 

PagedPoolAllocs 

The number of times a block was allocated from paged pool with this tag. 

PagedPoolFrees 

The number of times a block was deallocated to paged pool with this tag. 

PagedPoolUsage 

The number of bytes of paged pool used by blocks with this tag. 

NonPagedPool Allocs 

The number of times a block was allocated from nonpaged pool with this tag. 

NonPagedPoolFrees 

The number of times a block was deallocated to nonpaged pool with this tag. 

NonPagedPoolUsage 

The number of bytes of nonpaged pool used by blocks with this tag. 

Remarks 

This information class is only available if FLG_POOL_ENABLE_TAGGING was set in 
NtGlobalFlags at boot time. 

The data returned to the Systemlnformation buffer is a ULONG count of the number of 
tags followed immediately by an array of SYSTEM_POOL_TAG_INFORMATION. 

The data returned by this information class is displayed by the “poolmon” utility. 



SystemProcessorStatistics 



typedef struct _SYSTEM_PROCESSOR_STATISTICS { // Information Class 23 
ULONG ContextSwitches; 

ULONG DpcCount; 

ULONG DpcRequestRate; 

ULONG Timelncrement ; 

ULONG DpcBypassCount ; 

ULONG ApcBypassCount ; 

} SYSTEM_PROCESSOR_STATISTICS , *PSYSTEM_PROCESSOR_STATISTICS; 

Members 

ContextSwitches 

The number of context switches performed by the processor. 
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DpcCount 

The number of deferred procedure calls (DPC) that have been added to the processor’s 
DPC queue. 

DpcRequestRate 

The number of DPCs that have been added to the processor’s DPC queue since the 
last clock tick. 

Timelncrement 

The number of 100-nanosecond units between ticks of the system clock. 

DpcBypass Count 

The number of DPC interrupts that have been avoided. 

ApcBypass Count 

The number of kernel APC interrupts that have been avoided. 

Remarks 

An array of structures is returned, one per processor. 

The ReturnLength information is not set correctly (always contains zero). 



SystemDpcInformation 



typedef struct _SYSTEM_DPC_INFORMATION { // Information Class 24 
ULONG Reserved; 

ULONG MaximumDpcQueueDepth; 

ULONG MinimumDpcRate; 

ULONG AdjustDpcThreshold; 

ULONG IdealDpcRate; 

} SYSTEM_DPC_INFORMATION , *PSYSTEM_DPC_INFORMATION; 

Members 

MaximumDpcQueueDepth 

The maximum depth that the DPC queue should attain. If this depth is exceeded and 
no DPCs are active, a DPC interrupt is requested. 

MinimumDpcRate 

The minimum rate at which DPCs should be requested. If the current request rate is 
lower and no DPCs are active, a DPC interrupt is requested. 

AdjustDpcThreshold 

A parameter that affects the interval between retuning of the DPC parameters. 
IdealDpcRate 

The ideal rate at which DPCs should be requested. If the current rate is higher, mea- 
sures are taken to tune the DPC parameters (for example, by adjusting the maximum 
DPC queue depth). 
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Remarks 

This information class can be both queried and set. SeLoadDriverPrivilege is required 
to set the values. 

These parameters only affect Mediumlnportance and Highlmportance DPCs. 

The ReturnLength information is not set correctly (always contains zero). 



SystemLoadlmage 



typedef struct _SYSTEM_LOAD_IMAGE { // Information Class 26 
UNICODE_STRING ModuleName; 

PVOID ModuleBase; 

PVOID Unknown; 

PVOID EntryPoint; 

PVOID ExportDirectory ; 

} SYSTEM_LOAD_IMAGE , * P S Y ST EM_L0AD_ I MAG E ; 

Members 

ModuleName 

The full path in the native NT format of the module to load. Required on input. 

ModuleBase 

The base address of the module. Valid on output. 

Unknown 

Pointer to a data structure describing the loaded module. Valid on output. 

EntryPoint 

The address of the entry point of the module. Valid on output. 

ExportDirectory 

The address of the export directory of the module. Valid on output. 

Remarks 

This information class can only be set. Rather than setting any information (in a nar- 
row sense of “setting”), it performs the operation of loading a module into the kernel 
address space and returns information on the loaded module. 

After loading the module, MmPageEntireDriver (documented in the DDK) is called to 
make the entire module pageable. The module entry point is not called. 

This information class is valid only when ZwSetSystemlnformation is invoked from 
kernel mode. 



SystemUnloadlmage 



typedef struct _SYSTEM_UNLOAD_IMAGE { // Information Class 27 
PVOID ModuleBase; 

} SYSTEM_UNLOAD_IMAGE , *PSYSTEM_UNLOAD_IMAGE; 
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Members 

ModuleBase 

The base of a module. 



Remarks 

This information class can only be set. Rather than setting any information (in a nar- 
row sense of “setting”), it performs the operation of unloading a module from the 
kernel address space. 

Even if the module is a device driver, the D rive rUn load routine is not called. 

This information class is only valid when ZwSetSystemlnformation is invoked from 
kernel mode. 



SystemTimeAdjustment 



typedef struct _SYSTEM_QUERY_TIME_ADJUSTMENT { // Information Class 28 
ULONG TimeAdjustment; 

ULONG Maximumlncrement ; 

BOOLEAN TimeSynchronization; 

} SYSTEM_QUERY_TIME_ADJUSTMENT, *PSYSTEM_QUERY_TIME_ADJUSTMENT ; 

typedef struct _SYSTEM_SET_TIME_ADJUSTMENT { // Information Class 28 
ULONG TimeAdjustment; 

BOOLEAN TimeSynchronization; 

} SYSTEM_SET_TIME_ADJUSTMENT , *PSYSTEM_SET_TIME_ADJUSTMENT ; 

Members 

TimeAdjustment 

The number of 100-nanosecond units added to the time-of-day clock at each clock 
tick, if time adjustment is enabled. 

Maximumlncrement 

The maximum number of 100-nanosecond units between clock ticks. Also the num- 
ber of 100-nanosecond units per clock tick for kernel intervals measured in clock 
ticks. 

TimeSynchronization 

A boolean specifying that time adjustment is enabled when true. 

Remarks 

This information class can be both queried and set. SeSystemtimePrivilege is required 
to set the values. The structures for querying and setting values are different. 

The ReturnLength information is not set correctly (always contains zero). 
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SystemCrashDumpInformation 



typedef struct _SYSTEM_CRASH_DUMP_INFORMATION { // Information Class 32 
HANDLE CrashDumpSectionHandle; 

HANDLE Unknown; // Windows 2000 only 
} SYSTEM_CRASH_DUMP_INFORMATION , *PSYSTEM_CRASH_DUMP_INFORMATION ; 

Members 

CrashDumpSectionHandle 

A handle to the crash dump section. 

Unknown 

A handle to an unknown object. This information is only present in Windows 2000. 



Remarks 

If a crash dump section exists, a new handle to the section is created for the current 
process and returned in CrashDumpSectionHandle; otherwise, CrashDumpSectionHandle 
contains zero. 

In Windows 2000, SeCreatePagefilePrivilege is required to query the values. 



SystemExceptionlnformation 



typedef struct _SYSTEM_EXCEPTI0N_INF0RMATI0N { // Information Class 33 
UL0NG AlignmentFixupCount ; 

UL0NG ExceptionDispatchCount ; 

UL0NG FloatingEmulationCount ; 

UL0NG Reserved; 

} SYSTEM_EXCEPTI0N_INF0RMATI0N, *PSYSTEM_EXCEPTI0N_INF0RMATI0N ; 

Members 

AlignmentFixupCount 

The numbers of times data alignment had to be fixed up since the system booted. 
ExceptionDispatch Count 

The number of exceptions dispatched since the system booted. 
FloatingEmulationCount 

The number of times floating point instructions had to be emulated since the system 
booted. 



Remarks 

None. 
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SystemCrashDumpStatelnformation 



typedef struct _SYSTEM_CRASH_DUMP_STATE_INFORMATION { // Information Class 34 
ULONG CrashDumpSectionExists; 

ULONG Unknown; // Windows 2000 only 

} SYSTEM_CRASH_DUMP_STATE_INFOR MAT ION, *PSYSTEM_CRASH_DUMP_STATE_INFORMATION; 

Members 

CrashDumpSectionExists 

A boolean indicating whether a crash dump section exists. 

Unknown 

Interpretation unknown. This information is only present in Windows 2000. 



Remarks 

InWindows 2000, this information class can also be set if SeCreatePagefilePrivilege 
is enabled. 



SystemKernelDebuggerlnformation 



typedef struct _SYSTEM_KERNEL_DEBUGGER_INF0RMATI0N { // Information Class 35 
BOOLEAN DebuggerEnabled; 

BOOLEAN DebuggerNotPresent ; 

} SYSTEM_KERNEL_DEBUGGER_INF0RMATI0N , *PSYSTEM_KERNEL_DEBUGGER_INF0RMATI0N; 

Members 

DebuggerEnabled 

A boolean indicating whether kernel debugging has been enabled or not. 
DebuggerN o tPresent 

A boolean indicating whether contact with a remote debugger has been established 
or not. 



Remarks 

None. 



SystemContextSwitchlnformation 



typedef struct _SYSTEM_C0NTEXT_SWITCH_INF0RMATI0N { // Information Class 36 
ULONG ContextSwitches; 

ULONG ContextSwitchCounters[1 1 ] ; 

} SYSTEM_C0NTEXT_SWITCH_INF0RMATI0N, *PSYSTEM_C0NTEXT_SWITCH_INF0RMATI0N; 

Members 

ContextSwitches 

The number of context switches. 
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ContextSwitchCounters 

Normally contains zeroes; interpretation unknown. 



Remarks 

The resource kit utility “kernprof” claims to display the context switch counters (if the 
“-x” option is specified), but it only expects nine ContextSwitchCounters rather than 
eleven. It displays the information thus: 



Context Switch Information 

Find any processor 0 
Find last processor 0 
Idle any processor 0 
Idle current processor 0 
Idle last processor 0 
Preempt any processor 0 
Preempt current processor 0 
Preempt last processor 0 
Switch to idle 0 



SystemRegistryQuotalnformation 



typedef struct _SYSTEM_REGISTRY_QUOTA_INFORMATION { // Information Class 37 
ULONG RegistryQuota; 

ULONG RegistryQuotalnUse; 

ULONG PagedPoolSize; 



} SYSTEM_REGISTRY_QUOTA_INFORMATION, *PSYSTEM_REGISTRY_QUOTA_INFORMATION; 




Members 



RegistryQuota 

The number of bytes of paged pool that the registry may use. 

Registry Quotaln Use 

The number of bytes of paged pool that the registry is using. 

PagedPoolSize 

The size in bytes of the paged pool. 



Remarks 

This information class can be both queried and set. SelncreaseQuotaPrivilege is 
required to set the values. When setting, only the RegistryQuota value is used. 



SystemLoadAndCalllmage 



typedef struct _S YST E M_L0AD_AN D_CAL L_ I MAG E { // Information Class 38 
UNICODE_STRING ModuleName; 

} SYSTEM_LOAD_AND_CALL_IMAGE , *PSYSTEM_LOAD_AND_CALL_IMAGE ; 

Members 

ModuleName 

The full path in the native NT format of the module to load. 
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Remarks 

This information class can only be set. Rather than setting any information (in a nar- 
row sense of “setting”), it performs the operation of loading a module into the kernel 
address space and calling its entry point. 

The entry point routine is expected to be a stdcall routine taking two parameters 

(consistent with the Drive rEntry routine of device drivers); the call arguments are two 
zeroes. 

If the entry point routine returns a failure code, the module is unloaded. 

Unlike ZwLoadDriver, which loads the module in the context of the system process, 
ZwSetSystemlnformation loads the module and invokes the entry point in the context 
of the current process. 



SystemPrioritySeparation 



typedef struct _SYSTEM_PRIORI T Y_S E PAR AT I ON { // Information Class 39 
ULONG PrioritySeparation; 

} SYSTEM_PRIORITY_SEPARATION , *PSYSTEM_PRIORITY_SEPARATION ; 

Members 

PrioritySeparation 

A value that affects the scheduling quantum period of the foreground application. In 
Windows NT 4.0, PrioritySeparation takes a value between zero and two (the higher 
the value, the longer the quantum period). In Windows 2000, the low order six bits of 
PrioritySeparation are used to configure the scheduling quantum. 

Remarks 

None. 



SystemTimeZonelnformation 



typedef struct _SYSTEM_TIME_Z0NE_INF0RMATI0N { // Information Class 44 
LONG Bias; 

WCHAR StandardName[32] ; 

SYSTEMTIME StandardDate; 

LONG StandardBias; 

WCHAR DaylightName[32] ; 

SYSTEMTIME DaylightDate; 

LONG DaylightBias; 

} system_time_zone_information, *psystem_time_zone_information; 

Members 

Bias 

The difference, in minutes, between Coordinated Universal Time (UTC) and local 



time. 
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StandardName 

The name of the timezone when daylight saving time is not in effect. 

StandardDate 

A SYSTEMTIME structure specifying when daylight saving time ends. 

StandardBias 

The difference, in minutes, between UTC and local time when daylight saving time is 
not in effect. 

DaylightName 

The name of the timezone when daylight saving time is in effect. 

DaylightDate 

A SYSTEMTIME structure specifying when daylight saving time starts. 

DaylightBias 

The difference, in minutes, between UTC and local time when daylight saving time is 
in effect. 



Remarks 



This structure is identical to the TIME_ZONE_INFORMATION structure returned by the 
Win32 function GetTimeZonelnformation. 




SystemLookasidelnformation 



typedef struct _SYSTEM_LOOKASIDE_INFORMATION { // Information Class 45 
USHORT Depth; 

USHORT MaximumDepth; 

ULONG TotalAllocates; 

ULONG AllocateMisses; 

ULONG TotalFrees; 

ULONG FreeMisses; 

P00L_TYPE Type; 

ULONG Tag; 

ULONG Size; 

} SYSTEM_LOOKASIDE_INFORMATION , *PSYSTEM_LOOKASIDE_INFORMATION ; 

Members 

Depth 

The current depth of the lookaside list. 

MaximumDepth 

The maximum depth of the lookaside list. 

TotalAllocates 

The total number of allocations made from the list. 
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AllocateMisses 

The number of times the lookaside list was empty and a normal allocation was 
needed. 

TotalFrees 

The total number of allocations made from the list. 

FreeMisses 

The number of times the lookaside list was full and a normal deallocation was needed. 
Type 

The type of pool from which the memory for the lookaside list is allocated. Possible 
values are drawn from the enumeration P00L_TYPE: 

typedef enum _P00L_TYPE { 

NonPagedPool, 

PagedPool, 

NonPagedPoolMustSucceed , 

DontUseThisType, 

NonPagedPoolCacheAligned , 

PagedPoolCacheAligned , 

NonPagedPoolCacheAlignedMustS, 

MaxPoolType 

NonPagedPoolSession = 32, 

PagedPoolSession, 

NonPagedPoolMustSucceedSession, 

DontUseThisTypeSession , 

NonPagedPoolCacheAlignedSession, 

PagedPoolCacheAlignedSession , 

NonPagedPoolCacheAlignedMustSSession 
} P00L_TYPE; 



Tag 

The tag identifying allocations from the lookaside list 
Size 

The size of the blocks on the lookaside list. 

Remarks 

An array of structures are returned, one per lookaside list. The number of structures 
can be obtained by dividing the ReturnLength by the size of the structure. 

The lookaside lists reported on by this information class are only available to kernel 
mode code. Their purpose is to speed the allocation and deallocation of blocks of 
memory from paged and nonpaged pool. A nonpaged lookaside list is initialized by the 
routine ExInitializeNPagedLookasideList. 

Lookaside lists are documented in the DDK. 
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SystemSetTimeSlipEvent 



typedef struct _SYSTEM_SET_TIME_SLIP_EVENT { // Information Class 46 
HANDLE TimeSlipEvent ; 

} SYSTEM_SET_TIME_SLIP_EVENT, *PSYSTEM_SET_TIME_SLIP_EVENT; 

Members 

TimeSlipEvent 

A handle to an event object. The handle must grant EVENT_MODIFY_STATE access. 

Remarks 

This information class can only be set. SeSystemtimePrivilege is required to set the 
value. The TimeSlipEvent will be signalled when the kernel debugger has caused time 
to slip by blocking the system clock interrupt. 



SystemCreateSession 



typedef struct _SYSTEM_CREATE_SESSION { // Information Class 47 
ULONG Sessionld; 

} SYSTEM_CREATE_SESSION , *PSYSTEM_CREATE_SESSION ; 



Members 



Sessionld 

An identifier for the session. Valid on output. 



Remarks 

This information class can only be set. It creates a Windows Terminal Server session 
and assigns the session an identifier. This information class is valid only when 
Windows Terminal Server is running. In all other cases the return status is 
STATUS_INVALID_SYSTEM_SERVICE. 



SystemDeleteSession 



typedef struct _SYSTEM_DELETE_SESSION { // Information Class 48 
ULONG Sessionld; 

} SYSTEM_DELETE_SESSION , *PSYSTEM_DELETE_SESSION; 

Members 

Sessionld 

An identifier for the session 

Remarks 

This information class can only be set. This information class is valid only when 
Windows Terminal Server is running. In all other cases the return status is 
STATUS_INVALID_SYSTEM_SERVICE. 
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SystemRangeStartlnformation 



typedef struct _SYSTEM_RANGE_START_INFORMATION { // Information Class 50 
PVOID SystemRangeStart ; 

} SYSTEM_RANGE_START_I N FORMATI ON , * PS YSTEM_RANGE_ST ART_I N FORMATION ; 

Members 

SystemRangeStart 

The base address of the system (kernel) portion of the virtual address space. 

Remarks 

None. 



System Verifierlnformation 



Format unknown. 

Remarks 

This information class can be both queried and set. SeDebugPrivilege is required to set 
the values. 

This information class queries and sets information maintained by the device driver 
verifier. The “Driver Verifier” is described in the DDK documentation. 



SystemAddVerifier 



Format unknown. 

Remarks 

This information class is only valid when ZwSetSystemlnformation is invoked from 
kernel mode. 

This information class configures the device driver verifier. The “Driver Verifier” is 
described in the DDK documentation. 



SystemSessionProcessesInformation 



typedef struct _SYSTEM_SESSION_PROCESSES_INFORMATION { // Information Class 53 
ULONG Sessionld; 

ULONG BufferSize; 

PVOID Buffer; 

} SYSTEM_SESSION_PROCESSES_INFORMATION, *PSYSTEM_SESSION_PROCESSES_INFORMATION; 
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Members 

Sessionld 

The Sessionld for which to retrieve a list of processes and threads. 

BufferSize 

The size in bytes of the buffer in which to return the list of processes and threads. 

Buffer 

Points to a caller- allocated buffer or variable that receives the list of processes and 
threads. 

Remarks 

Unlike other information classes, this information class uses the Systemlnformation 
argument of ZwQuerySystemlnformation as an input buffer. 

The information returned is in the same format as that returned by 
SystemProcessesAndThreadsInformation, but contains information only on the 
processes in the specified session. 

The following information classes are only available in “checked” versions of the 
kernel. 



SystemPoolBlocksInformation 



typedef struct _SYSTEM_P00L_BL0CKS_INF0RMATI0N { // Info Classes 14 and 15 
ULONG PoolSize; 

PVOID PoolBase; 

USHORT Unknown; 

ULONG NumberOf Blocks; 

SYSTEM_P00L_BL0CK PoolBlocks [ 1 ] ; 

} SYSTEM_P00L_BL0CKS_INF0RMATI0N, *PSYSTEM_P00L_BL0CKS_INF0RMATI0N; 

typedef struct _SYSTEM_P00L_BL0CK { 

BOOLEAN Allocated; 

USHORT Unknown; 

ULONG Size; 

CHAR Tag [4]; 

} SYSTEM_P00L_BL0CK, *PSYSTEM_P00L_BL0CK; 

Members 

PoolSize 

The size in bytes of the pool. 



PoolBase 

The base address of the pool. 

Unknown 

The alignment of the pool; interpretation uncertain. 
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NumberOfBlocks 

The number of blocks in the pool. 

PoolBlocks 

An array of SYSTEM_POOL BLOCK structures describing the blocks in the pool. The num- 
ber of elements in the array is available in the NumberOfBlocks member. 

The members of SYSTEM_POOL_BLOCK aredescribed in the following section. 

Allocated 

A boolean indicating whether this is an allocated or free block. 



Unknown 

Interpretation unknown. 

Size 

The size in bytes of the block. 

Tag 

The four character tag string identifying the contents of the pool allocation. 

Remarks 

Information class 14 returns data on the paged pool and information class 15 returns 
data on the nonpaged pool. 

The paged and nonpaged pools reported on by these information classes are only 
available to kernel mode code. Blocks are allocated from paged and nonpaged pool by 
the routines ExAllocatePoolXxx.The use of pool memory is documented in the DDK. 



SystemMemoryUsagelnformation 



typedef struct _SYSTEM_MEMORY_USAGE_INFORMATION { // Info Classes 25 and 29 
ULONG Reserved; 

PVOID EndOfData; 

SYSTEM_MEMORY_USAGE MemoryUsage [ 1 ] ; 

} SYSTEM JVIEMORY_USAGE_INFORMATION , *PSYSTEM_MEMORY_USAGE_INFORMATION; 

typedef struct _SYSTEM_MEMORY_USAGE { 

PVOID Name; 

USHORT Valid; 

USHORT Standby; 

USHORT Modified; 

USHORT PageTables; 

} SYSTEM_MEMORY_USAGE , * PSYSTEM_MEMORY_USAGE ; 
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Members 

EndOfData 

A pointer to the end of the valid data in the Systemlnf ormation buffer. 

MemoryUsage 

An array of SYSTEM_MEMORY_USAGE structures describing the usage of physical memory 
The number of elements in the array is deducible from the EndOfData member. 

The members of SYSTEM_MEMORY_USAGE are described in the following sections. 

Name 

The name of the object using the memory. This can be either a Unicode or ANSI 
string. 



Valid 

The number of valid pages used by the object. If the object is a process, this is the 
number of valid private pages. 

Standby 

The number of pages recently used by the object, that are now on the Standby list. 

Modified 

The number of pages recently used by the object which are now on the Modified list. 

PageTables 

The number of pagetable pages used by the object. The only objects that use pageta- 
bles are processes. On an Intel platform using large (4-MByte) pages, the pagetables are 
charged against nonpaged pool rather than processes. 

Remarks 

Information class 29 does not provide the information on the pages in the Standby 
and Modified lists. 

There is no indication of whether the name is a Unicode or ANSI string other than 
the string data itself (for example, if every second byte is zero, the string must be 
Unicode). 

Information class 25 is able to account for the use of almost all the physical memory 
in the system. The difference between sum of the Valid, Standby and Modified pages 
and the NumberOf PhysicalPages (returned by the SystemBasicInformation class) is nor- 
mally close to the number of pages on the Free and Zeroed memory lists. 



Example 1.1: A Partial ToolHelp Library Implementation 



#include "ntdll.h" 
#include <tlhelp32.h> 
#include <stdio.h> 



struct ENTRIES { 
ULONG Offset; 





1996 CHOI 11/19/99 12:24 PM Page 43 



System Information and Control: Example 1.1 : A Partial ToolHelp Library Implementation 



43 



ULONG Count; 

ULONG Index; 

ENTRIES ( ) : Offset(0), Count(0), lndex(0) {} 

ENTRIES(ULONG m, ULONG n) : Offset(m), Count(n), lndex(0) {} 



enum EntryType { 
ProcessType, 
ThreadType, 
MaxType 



NT: : PSYSTEM_PROCESSES GetProcessesAndThreads ( ) 

{ 

ULONG n = 0x100; 

NT: :PSYSTEM_PROCESSES sp = new NT: :SYSTEM_PROCESSES[n] ; 

while (NT: :ZwQuerySystemInformation( 

NT : :SystemProcessesAndThreadsInformation, 
sp, n * sizeof *sp, 0) 

== STATUS_INFO_LENGTH_MISMATCH) 
delete [] sp, sp = new NT: :SYSTEM_PROCESSES[n = n * 2]; 

return sp; 

} 

ULONG ProcessCount (NT : : PSYSTEM_PROCESSES sp) 

{ 

ULONG n = 0; 
bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) 
n++, done = p->NextEntryDelta == 0; 

return n; 

} 

ULONG ThreadCount (NT : : PSYSTEM_PROCESSES sp) 

{ 

ULONG n = 0; 
bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT: :PSYSTEM_PROCESSES (PCHAR (p) + p->NextEntryDelta) ) 
n += p->ThreadCount , done = p->NextEntryDelta == 0; 

return n; 

} 

VOID AddProcesses ( PPR0CESSENTRY32 pe, NT: : PSYSTEM_PROCESSES sp) 

{ 

bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT: :PSYSTEM_PROCESSES (PCHAR (p) + p->NextEntryDelta) ) { 

pe->dwSize = sizeof *pe; 
pe->cntUsage = 0; 
pe->th32ProcessID = p->ProcessId; 
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pe->th32DefaultHeapID = 0; 

pe->th32ModuleID = 0; 

pe->cntThreads = p->ThreadCount ; 

pe->th32ParentProcessID = p->InheritedFromProcessId; 

pe->pcPriClassBase = p->BasePriority ; 

pe->dwFlags = 0; 

sprintf (pe->szExeFile, *ls" , 

p->ProcessName. Length / 2, p->ProcessName. Buffer) ; 



pe++; 

done = p->NextEntryDelta == 0; 

} 

} 

VOID AddThreads ( PTHREADENTRY32 te, NT: : PSYSTEM_PROCESSES sp) 

{ 

bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) { 

for (ULONG i = 0; i < p->ThreadCount; i++) { 

te->dwSize = sizeof *te; 
te->cntUsage = 0; 

te->th32ThreadID = DWORD(p->Threads[i] .Clientld.UniqueThread) ; 
te->th320wnerProcessID = p->ProcessId; 
te->tpBasePri = p->Threads[i] .BasePriority; 
te->tpDeltaPri = p->Threads[i] .Priority 

- p->Threads[i] .BasePriority; 
te->dwFlags = 0; 

te++; 

} 

done = p->NextEntryDelta == 0; 

} 

} 

template<class T> 

BOOL GetEntry (HANDLE hSnapshot, T entry, bool first, EntryType type) 

{ 

ENTRIES *entries = ( ENTRIES* )MapViewOf File ( hSnapshot , FILE_MAP_WRITE, 

0, 0, 0); 

if (entries == 0) return FALSE; 

BOOL rv = TRUE; 

entries[type] . Index = first ? 0 : entries[type] . Index + 1; 

if (entries[type] . Index >= entries[type] .Count) 

SetLastError (ERR0R_N0_M0RE_FILES) , rv = FALSE; 

if (entry->dwSize < sizeof *entry) 

SetLastError (ERROR_INSUFFICIENT_BUFFER) , rv = FALSE; 

if (rv) 

*entry = T ( PCHAR ( entries )+entries[ type] .Offset) [entries [type] . Index] ; 
UnmapViewOf File(entries) ; 
return rv; 

} 



1996 CHOI 11/19/99 12:24 PM Page 45 



System Information and Control: Example 1.1: A Partial ToolHelp Library Implementation 



45 



HANDLE 

WINAPI 

CreateToolhelp32Snapshot (DWORD flags, DWORD) 

{ 

NT: :PSYSTEM_PROCESSES sp = 

(flags & (TH32CS_SNAPPR0CESS j TH32CS_SNAPTHREAD) ) 

? GetProcessesAndThreads( ) : 0; 

ENTRIES entries[MaxType] ; 

ULONG n = sizeof entries; 

if (flags & TH32CS_SNAPPR0CESS ) { 

entries[ProcessType] = ENTRIES(n, ProcessCount (sp) ) ; 
n += entries[ProcessType] .Count * sizeof (PR0CESSENTRY32) ; 

} 

if (flags & TH32CS_SNAPTHREAD ) { 

entries[ThreadType] = ENTRIES(n, ThreadCount (sp) ) ; 
n += entries[ThreadType] .Count * sizeof (THREADENTRY32) ; 

} 

SECUR ITY_ATTR I BUTES sa = {sizeof sa, 0, (flags & TH32CS_INHERIT) != 0}; 

HANDLE hMap = CreateFileMapping (HANDLE (0XFFFFFFFF) , &sa, 

PAG E_R E ADWR I T E j SEC_COMMIT, 0, n, 0); 

ENTRIES *p = ( ENTRIES* )MapViewOf File ( hMap, FILE_MAP_WRITE, 0, 0, 0); 

for (int i = 0; i < MaxType; i++) p[i] = entries[i]; 

if (flags & TH32CS_SNAPPR0CESS ) 

AddProcesses(PPR0CESSENTRY32(PCHAR(p) + entries[ProcessType] .Offset) , 

sp) ; 

if (flags & TH32CS_SNAPTHREAD ) 

AddThreads ( PTHREADENTRY32 ( PCHAR ( p ) + entries[ThreadType] .Offset) , 

sp) ; 

UnmapViewOf File(p) ; 
if (sp) delete [] sp; 
return hMap; 

} 

BOOL 

WINAPI 

Thread32First (HANDLE hSnapshot, PTHREADENTRY32 te) 

{ 

return GetEntry (hSnapshot , te, true, ThreadType); 

} 

BOOL 

WINAPI 

Thread32Next (HANDLE hSnapshot, PTHREADENTRY32 te) 

{ 

return GetEntry (hSnapshot , te, false, ThreadType); 

} 

BOOL 

WINAPI 

Process32First (HANDLE hSnapshot, PPR0CESSENTRY32 pe) 

{ 

return GetEntry (hSnapshot , pe, true, ProcessType) ; 

} 
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BOOL 

WINAPI 

Process32Next (HANDLE hSnapshot, PPR0CESSENTRY32 pe) 

{ 

return GetEntry (hSnapshot , pe, false, ProcessType) ; 

} 

ZwQuerySystemlnformation with an information class of 
SystemProcessesAndThreadsInformation returns a superset of the information 
concerning processes and threads that is available via the ToolHelp library (if it were 
implemented in Windows NT 4.0). Example 1.1 uses this information class to imple- 
ment a subset of the ToolHelp library; the remaining functions of the ToolHelp library 
are addressed in later chapters. 

The Win32 function CreateToolhelp32Snapshot returns a handle to a snapshot of the 
processes and threads (and modules and heaps) in the system. The Win32 documenta- 
tion states that this handle (and the snapshot itself) is freed by calling CloseHandle. 
ZwQuerySystemlnformation also returns a “snapshot,” but this snapshot is just data in a 
caller-supplied buffer. To implement the documented behavior of 
CreateToolhelp32Snapshot, it is necessary to encapsulate the information returned by 
ZwQuerySystemlnformation in a kernel object so that CloseHandle can free it. 

The only suitable kernel object is a section object (known as a file mapping object by 
Win32). The idea is to create a paging-file backed section object and then map a view 
of this section into the address space so that the information returned from 
ZwQuerySystemlnformation can be copied to it. The view is then unmapped so that 
closing the section handle will free the snapshot (mapped views prevent the section 
object from being deleted). 

The routines that return information from the snapshot must then just map the sec- 
tion, copy the relevant data to the caller-supplied buffer, and unmap the section. 



Example 1.2: Listing Open Handles of a Process 



#include "ntdll.h" 

#include <stdlib.h> 

#include <stdio.h> 

#include <vector> 

#include <map> 

#pragma warning(disable:4786) // identifier was truncated in the debug info 
Struct OBJ ECTS_AND_TYPES { 

std: :map<UL0NG, NT: : PSYSTEM_OBJECT_TYPE_IN FORMATION, std : : less<UL0NG> > 
types; 

std: :map<PV0ID, NT: : PSYSTEM_0BJECT_INF0RMATI0N, std : : less<PV0ID> > 
objects; 



std: : vector<NT : :SYSTEM_HANDLE_INFORMATION> GetHandlesQ 

{ 

ULONG n; 

PULONG p = new ULONG [ n = 0x100]; 

while (NT : : ZwQuerySystemlnformation (NT : :SystemHandleInformation, 

p, n * sizeof *p, 0) 
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== STATUS_INFO_LENGTH_MISMATCH) 
delete [] p, p = new UL0NG[n *= 2]; 

NT: :PSYSTEM_HANDLE_INFORMATION h = NT: :PSYSTEM_HANDLE_INFORMATION(p + 1); 
return std: :vector<NT: :SYSTEM_HANDLE_INFORMATION>(h, h + *p) ; 



OBJ ECTS_AND_TYPES GetObj ectsAndTypes ( ) 

{ 

ULONG n; 

PCHAR p = new CHAR [ n = 0x1000]; 

while (NT : :ZwQuerySystemInformation(NT : :SystemObjectInformation, 

p, n * sizeof *p, 0) 

== STATUS_INFO_LENGTH_MISMATCH) 

delete [] p, p = new CHAR[n *= 2]; 

OBJ ECTS_AND_TYPES oats; 

for (NT: : PSYSTEM_OBJECT_TYPE_INFORMATION 

t = NT: :PSYSTEM_OBJECT_TYPE_INFORMATION(p) ; ; 

t = NT: :PSYSTEM_OBJECT_TYPE_INFORMATION(p + t->NextEntryOffset) ) { 



oats.types[t->TypeNumber] = t; 




for 



(NT: : PSYSTEM_OBJECT_INFORMATION 

o = NT : : PSYSTEM_OBJECT_INFORMATION ( PCHAR (t ->Name . Buffer) 

+ t->Name.Maximuml_ength) ; ; 
0 = NT: :PSYSTEM_OBJECT_INFORMATION(p + o->NextEntryOff set ) ) { 



oats.objects[o->Object] = o; 



if (o->NextEntryOffset == 0) break; 

} 

if (t ->NextEntryOff set == 0) break; 



return oats; 

} 

int main(int argc, char *argv[]) 

{ 

if (argc == 1 ) return 0; 

ULONG pid = strtoul(argv[ 1 ] , 0, 0); 

OBJECTS_AND_TYPES oats = GetObj ectsAndTypes () ; 

std: :vector<NT: :SYSTEM_HANDLE_INFORMATION> handles = GetHandles ( ) ; 

NT: :SYSTEM_OBJECT_INFORMATION defobj = {0}; 

printf( "Object Hnd Access FI Atr #H #P Type Name\n"); 

for ( std : : vector<NT : : SYSTEM_HANDLE_INFORMATION> : : iterator 
h = handles. begin( ) ; h != handles. end( ) ; h++) { 

if (h->ProcessId == pid) { 



NT: : PSYSTEM_OBJECT_TYPE_INFORMATION 




47 
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t = oats.types[h->ObjectTypeNumber] ; 
NT: :PSYSTEM_OBJECT_INFORMATION 
o = oats.objects[h->Object] ; 



if (o == 0) o = &defobj ; 



printf("%p %04hx %61x %2x %3hx %31d %41d %-14.*S %.*S\n", 

b->Ob]ect, b->Handle, h ->Gr'antedAccess , int(h->Flags) , 
o->Flags, o->HandleCount, o->PointerCount, 
t->Name. Length, t->Name. Buffer, 
o->Name. Length, o->Name. Buffer) ; 

} 

} 

return 0; 

} 

Example 1.2 assumes that the NtGlobalFlag FLG_MAINTAIN_OBJECT_TYPELIST was set at 
boot time. An alternative method of obtaining a list of open handles using a combina- 
tion of ZwQuerySystemlnformation and ZwQueryObject appearsin Chapter 2, “Objects, 
Object Directories, and Symbolic Links,” in Example 2.1. 

The program uses the address of the kernel object to which a handle refers to corre- 
late the information returned by the information classes SystemHandlelnformation and 
SystemObj ectlnformation; a Standard Template Library (STL)map is used for this 
purpose. 

The list of handles in the system is scanned for handles owned by a particular process 
id, and then information about the handle and the object to which it refers is dis- 
played. 



ZwQuerySystemEnvironmentValue 



ZwQuerySystemEnvironmentValue queries the value of a system environment variable 
stored in the non-volatile (CMOS) memory of the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySystemEnvironmentValue ( 

IN PUNICODE_STRING Name, 

OUT PVOID Value, 

IN ULONG ValueLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

Name 

The name of system environment value to be queried. 

Value 

Points to a caller-allocated buffer or variable that receives the requested system 
environment value. 

ValueLength 

The size in bytes of Value. 
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ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Value. If ValueLength is too small to contain the available data, the variable is set to the 
number of bytes required for the available data. If this information is not needed by 
the caller, ReturnLength may be specified as a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_BUFFER_OVERFLOW, or STATUSJJNSUCCESSFUL. 

Related Win32 Functions 

None. 

Remarks 

SeSystemEnvironmentPrivilege is required to query system environment values. 

The information returned in Buffer is an array ofWCHAR.The ReturnLength value con- 
tains the length of the string in bytes. 

ZwQuerySystemEnvironmentValue queries environment values stored in CMOS. The 
standard Hardware Abstraction Layer (HAL) for the Intel platform only supports one 
environment value, “LastKnownGood,” which takes the values “TRUE” and “FALSE.” It is 
queried by writing Oxb to port 0x70 and reading from port 0x71. A value of zero is 
interpreted as “FALSE,” other values as “TRUE.” 



ZwSetSystemEnvironmentValue 



ZwSetSystemEnvironmentValue sets the value of a system environment variable stored in 
the non-volatile (CMOS) memory of the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetSystemEnvironmentValue ( 

IN PUNICODE_STRING Name, 

IN PUNICODE_STRING Value 

); 



Parameters 

Name 

The name of system environment value to be set. 

Value 

The value to be set. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD or 



STATUS UNSUCCESSFUL. 
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Related Win32 Functions 

None. 

Remarks 

SeSystemEnvironmentPrivilege is required to set system environment values. 

ZwSetSystemEnvironmentValue sets environment values stored in CMOS. The standard 
HAL for the Intel platform only supports one environment value, “Last KnownGood,” 
which takes the values “TRUE” and “FALSE.” It is set by writing Oxb to port 0x70 and 
writing 0 (for “FALSE”) or 1 (for “TRUE”) to port 0x71. 



ZwShutdownSystem 



ZwShutdownSystem shuts down the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwShutdownSystem ( 

IN SHUTD0WN_ACTI0N Action 

); 



Parameters 

Action 

The action to be performed after shutdown. Permitted values are drawn from the 
enumeration SHUTD0WN_ACTI0N. 

typedef enum _SHUTD0WN_ACTI0N { 

ShutdownNoReboot , 

ShutdownReboot , 

ShutdownPowerOff 
} SHUTD0WN_ACTI0N ; 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

ExitWindows ( Ex ) , InitiateSystemShutdown. 

Remarks 

SeShutdownPrivilege is required to shut down the system. 

User-mode applications and services are not informed of the shutdown (drivers of 
devices that have registered for shutdown notification by calling 
IoRegisterShutdownNotif ication are informed). 

The system must have hardware support for power-off if the power-off action is to be 
used successfully. 
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ZwSystemDebugControl 



ZwSystemDebugControl performs a subset of the operations available to a kernel mode 
debugger. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSystemDebugControl ( 

IN DEBUG_C0NTR0L_C0DE ControlCode, 

IN PVOID InputBuffer OPTIONAL, 

IN ULONG InputBufferLength, 

OUT PVOID OutputBuffer OPTIONAL, 

IN ULONG OutputBufferLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ControlCode 

The control code for operation to be performed. Permitted values are drawn from the 
enumeration DEBUG_C0NTR0L_C0DE. 

typedef enum _DEBUG_C0NTR0L_C0DE { 

DebugGetTracelnformation = 1, 

DebugSetlnternalBreakpoint , 

DebugSetSpecialCall, 

DebugClearSpecialCalls , 

DebugQuerySpecialCalls , 

DebugDbgBreakPoint 
} DEBUG_C0NTR0L_C0DE ; 

InputBuffer 

Points to a caller- allocated buffer or variable that contains the data required to perform 
the operation. This parameter can be null if the ControlCode parameter specifies an 
operation that does not require input data. 

InputBufferLength 

The size in bytes of InputBuffer. 

OutputBuffer 

Points to a caller-allocated buffer or variable that receives the operation s output data. 
This parameter can be null if the ControlCode parameter specifies an operation that 
does not produce output data. 

OutputBufferLength 

The size in bytes of OutputBuffer. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
OutputBuffer. If this information is not needed, ReturnLength may be a null pointer. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
ST ATUS_I NVAL I D_I N F0_CLASS or STATUS_INFO_LENGTH JflISMATCH. 

Related Win32 Functions 

None. 



Remarks 

SeDebugPrivilege is required to use ZwSystemDebugControl in Windows 2000. 

ZwSystemDebugControl allows a process to perform a subset of the functions available to 
a kernel mode debugger. 

The system should be booted from a configuration that has the boot.ini “/DEBUG” (or 
equivalent) option enabled; otherwise a kernel debugger variable needed for the cor- 
rect operation of internal breakpoints is not initialized. 

The data structures used by ZwSystemDebugControl are defined in windbgkd.h (includ- 
ed with the Platform SDK). An up-to-date copy of this file is needed to compile the 
code in Examples 1.3 and 1.4. One of the structures used by ZwSystemDebugControl 
includes a union that has grown over time, and ZwSystemDebugControl checks that the 
input/ output buffers are large enough to hold the largest member of the union. 

DebugGetTracelnformation 

typedef struct _DBGKD_GET_INTERNAL_BREAKPOINT { // DebugGetTracelnformation 
DW0RD_PTR BreakpointAddress; 

DWORD Flags; 

DWORD Calls; 

DWORD MaxCallsPerPeriod; 

DWORD Minlnstructions; 

DWORD Maxlnstructions; 

DWORD Totallnstructions; 

} DBGKD_GET_INTERNAL_BREAKPOINT, *PDBGKD_GET_INTERNAL_BREAKPOINT ; 

#def ine DBGKD_INTERNAL_BP_FLAG_COUNTONLY 0x01 // don't count instructions 
#define DBGKD_INTERNAL_BP_FLAG_INVALID 0x02 // disabled BP 
#def ine DBGKD_INTERNAL_BP_FLAG_SUSPENDED 0x04 // temporarily suspended 
#def ine DBGKD_INTERNAL_BP_FLAG_DYING 0x08 // kill on exit 

DebugGetTracelnformation does not require an InputBuffer and returns an array of 
DBGKD_GET_INTERNAL_BREAKPOINT structures in the output buffer, one for each of the 
internal breakpoints set. 

Instruction counting counts the instructions from the breakpoint until the return from 
the routine containing the breakpoint. Ideally, the breakpoint should be placed at the 
beginning of a routine. The user mode debugger (windbg, cdb, ntsd) command “wt” 
performs user mode instruction counting. 

If instruction counting is enabled, Minlnstructions contains the minimum number of 
instructions encountered when executing the routine, Maxlnstructions contains the 
maximum, and Totallnstructions contains the total number of instructions executed 
by all invocations of the routine (since the breakpoint was inserted). 

Calls is the number of times the breakpoint has been encountered. 
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Flags indicates whether instruction counting is enabled and whether the breakpoint 
has been suspended. 



DebugSetlnternalBreakpoint 

typedef struct _D BG KD_M AN I P U L AT E_ST AT E { 

DWORD ApiNumber; 

WORD ProcessorLevel; 

WORD Processor; 

DWORD ReturnStatus; 
union { 

DBGKD_READ_MEMORY ReadMemory; 

DBGKD_WRITE_MEMORY WriteMemory; 

DBGKD_READ_MEM0RY64 ReadMemory64 ; 

DBGKD_WRITE_MEM0RY64 WriteMemory64 ; 

DBGKD_GET_CONTEXT GetContext; 

DBGKD_SET_CONTEXT SetContext; 

DBGKD_WRITE_BREAKPOINT WriteBreakPoint ; 

DBGKD_RESTORE_BREAKPOINT RestoreBreakPoint ; 

DBGKD_CONTINUE Continue; 

DBGKD_C0NTINUE2 Continue2; 

DBGKD_READ_WRITE_IO ReadWritelo; 

DBGKD_READ_WRITE_IO_EXTENDED ReadWriteloExtended ; 

DBGKD_QUERY_SPECIAL_CALLS QuerySpecialCalls ; 

DBGKD_SET_SPECIAL_CALL SetSpecialCall ; 

DBGKD_SET_INTERNAL_BREAKPOINT SetlnternalBreakpoint ; 
DBGKD_GET_INTERNAL_BREAKPOINT GetlnternalBreakpoint ; 

DBGKD_GET_VERSION GetVersion; 

DBGKD_BREAKPOINTEX BreakPointEx; 

DBGKD_PAGEIN Pagein; 

DBGKD_READ_WRITE_MSR ReadWriteMsr ; 

} u; 

} DBGKD_MAN I PULATE_STATE , * P D BG KD_MAN I P U L AT E_ST AT E ; 

typedef struct _DBGKD_SET_INTERNAL_BREAKPOINT { // DebugSetlnternalBreakpoint 
DW0RD_PTR BreakpointAddress; 

DWORD Flags; 

} DBGKD_SET_INTERNAL_BREAKPOINT , *PDBGKD_SET_INTERNAL_BREAKPOINT; 

DebugSetlnternalBreakpoint does not require an OutputBuffer and expects the 
InputBuffer to point to a DBGKD_MANIPULATE_STATE structure. The only values in this 
structure that are required are the two values in the DBGKD_SET_INTERNAL_BREAKPOINT 
structure. InputBuff erLength is the size of the DBGKD_MANIPULATE_STATE structure. 

BreakpointAddress is the address of the breakpoint. If a breakpoint already exists at this 
address, the Flags are used to manipulate the breakpoint, otherwise a new breakpoint 
is established. Breakpoints are deleted by setting the DBGKD_INTERNAL_BP_FLAG_INVALID 
flag and are temporarily suspended by setting the DBGKD_INTERNAL_BP_FLAG_SUSPENDED 
flag. The counting or non-counting nature of the breakpoint can be controlled by 
setting or clearing the DBGKD_INTERNAL_BP_FLAG_COUNTONLY flag. 

Breakpoints can be set at any address, but if the address is not at the start of an instruc- 
tion then an STATUS_ILLEGAL_INSTRUCTION exception may be raised resulting in a sys- 
tem crash. The intention is that breakpoints should be set at the start of routines but, 
particularly if instruction counting is disabled, this is not essential. 
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DebugSetSpecialCall 

typedef struct _DBGKD_SET_SPECIAL_CALL { // DebugSetSpecialCall 
DWORD SpecialCall; 

} DBGKD_SET_SPECIAL_CALL , *PDBGKD_SET_SPECIAL_CALL ; 

DebugSetSpecialCall does not require an OutputBuffer and expects the InputBuffer 
to point to a DBGKD_MANIPULATE_STATE structure. The only value in this structure that is 
required is the value in the DBGKD_SET_SPECIAL_CALL structure. InputBuff erLength must 
be four rather than the size of the DBGKD_MANIPULATE_STATE structure — this is a bug. 

“Special Calls” are routines that should be treated specially when counting the instruc- 
tions executed by some routine. The special calls set by the kernel debugger are: 

HAL ! @Kf LowerIrql@4 

HAL ! @Kf ReleaseSpinLock@8 

HAL ! @HalRequestSof twarelnterrupt@4 

NTOSKRNL ! SwapContext 

NTOSKRNL ! @KiUnlockDispatcherDatabase@4 

Whether the members of this list are necessary or sufficient to ensure correct opera- 
tion of the instruction counting feature is difficult to say. 



DebugClearSpecialCalls 



DebugClearSpecialCalls requires neither an InputBuffer nor an OutputBuff er. It clears 
the list of special calls. 



DebugQuerySpecialCalls 



typedef struct _DBGKD_QUERY_SPECIAL_CALLS { // DebugQuerySpecialCalls 
DWORD NumberOfSpecialCalls; 

// DWORD SpecialCalls[] ; 

} DBGKD_QUERY_SPECIAL_CALLS , *PDBGKD_QUERY_SPECIAL_CALLS; 



DebugQuerySpecialCalls does not require an InputBuffer and expects the OutputBuffer 
to point to a buffer large enough to hold a DBGKD_MANIPULATE_STATE structure and an 
array of DWORDs, one per special call. It returns a list of the special calls. 



DebugDbgBreakPoint 

DebugDbgBreakPoint requires neither an InputBuffer nor an OutputBuffer. If the kernel 
debugger is enabled it causes a kernel mode debug break point to be executed. This 
debug control code is only valid in Windows 2000. 

The code in Examples 1.3 and 1.4 demonstrates how to set internal breakpoints and 
get trace information. 



Example 1.3: Setting an Internal Breakpoint 



#include "ntdll.h" 

#include "windbgkd . h" 

#include <imagehlp.h> 

#include <stdlib.h> 

void LoadModules( ) 

{ 

ULONG n; 

NT : :ZwQuerySystemInformation(NT : :SystemModuleInformation, 
&n, 0, &n); 
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PULONG p = new ULONG [ n ] ; 

NT : :ZwQuerySystemInformation(NT : :SystemModuleInformation, 
p, n * sizeof *p, 0) ; 

NT: : PSYSTEM_MODULE_INFORMATION module 

= NT: :PSYSTEM_MODULE_INFORMATION(p +1); 

for (ULONG i = 0; i < *p; i++) 

SymLoadModule(0, 0, module[i] . ImageName, 

module[i] . ImageName + module[i] .ModuleNameOff set , 
ULONG ( module [i] .Base) , module[i] .Size) ; 



delete [] p; 

} 

DWORD GetAddress(PSTR expr) 

{ 

PCHAR s; 

ULONG n = strtoul(expr, &s, 16); 

if (*s == 0) return n; 

IMAGEHLP_SYMBOL symbol; 

symbol. SizeOf Struct = sizeof symbol; 
symbol. MaxNameLength = sizeof symbol. Name; 

return SymGetSymFromName(0, expr, &symbol) == TRUE ? symbol. Address : 0; 

} 

void SetSpecialCall( DWORD addr) 

{ 

DBGKD_MAN I PULATE_STATE op = {0}; 

op. u .SetSpecialCall.SpecialCall = addr; 

NT: :ZwSystemDebugControl(NT: :DebugSetSpecialCall, &op, 4, 0, 0, 0); 

} 

void SetSpecialCalls( ) 

{ 

DBGKD_MAN I PULATE_STATE op[4]; 

NT : :ZwSystemDebugControl(NT : :DebugQuerySpecialCalls, 

0, 0, op, sizeof op, 0) ; 

if (op[0] .u.QuerySpecialCalls.NumberOfSpecialCalls == 0) { 
SetSpecialCall(GetAddress( "HALIKf Lowerlrql" ) ) ; 
SetSpecialCall(GetAddress( "HALIKfReleaseSpinLock" ) ) ; 
SetSpecialCall(GetAddress( "HALlHalRequestSoftwarelnterrupt " ) ) ; 
SetSpecialCall(GetAddress( "NTOSKRNLlSwapContext" ) ) ; 
SetSpecialCall(GetAddress( "NTOSKRNL! KiUnlockDispatcherDat abase" ) ) ; 

} 

} 

int main(int argc, char *argv[]) 

{ 

if (argc < 2) return 0; 

NT:: SYSTEM_KERNEL_DEBUGGER_INFORMATION kd; 

NT : :ZwQuerySystemInformation(NT : :SystemKernelDebuggerInformation, 

&kd, sizeof kd, 0) ; 

if (kd.DebuggerEnabled == FALSE) return 0; 
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EnablePrivilege(SE_DEBUG_NAME) ; 

SymInitialize(0, 0, FALSE); 

SymSetOptions(SymGetOptions( ) | SYMOPT_DEFERRED_LOADS) ; 

LoadModules( ) ; 

SetSpecialCalls( ) ; 

DBGKD_MAN I PULATE_STATE op = {0}; 

op.u.SetlnternalBreakpoint.BreakpointAddress = GetAddress(argv[1 ] ) ; 

op. u.SetlnternalBreakpoint. Flags = argc < 3 ? 0 : strtoul(argv[2] , 0, 16); 

NT : :ZwSystemDebugControl(NT : :DebugSetInternalBreakpoint , 

&op, sizeof op, 0, 0, 0) ; 



return 0; 

} 

If the kernel debugger is not enabled, an important debugger variable is not initialized. 
Therefore, Example 1.3 first uses ZwQuerySystemlnformation to check the debugger 
status and if it is enabled, the program then sets the special calls and creates or updates 
a breakpoint. 

The program also demonstrates how to obtain a list of the kernel modules and their 
base addresses. This information is needed by the Imagehlp API routines, which are 
used to translate symbolic names into addresses. 

The program assumes that SymLoadModule will find the correct symbol files; if this rou- 
tine finds the wrong symbol files (for example, symbols for a checked rather than free 
build), a system crash is almost guaranteed. 



Example 1.4: Getting Trace Information 



#include "ntdll.h" 

#include "windbgkd . h" 

#include <stdio.h> 

int main() 

{ 

DBGKD_GET_INTERNAL_BREAKPOINT bp [20] ; 

ULONG n; 

EnablePrivilege(SE_DEBUG_NAME) ; 

NT : :ZwSystemDebugControl(NT : :DebugGetTraceInformation, 

0, 0, bp, sizeof bp, &n) ; 

for (int i = 0; i * sizeof ( DBGKD_GET_INTERNAL_BREAKPOI NT ) < n; i++) 

printf("%lx %lx %ld %ld %ld %ld %ld\n", 

bp [ i ] .BreakpointAddress, bp[i] .Flags, 
bp [ i ] .Calls, bp [ i ] .MaxCallsPerPeriod, 
bp [ i ] .Minlnstructions, bp [ i ] .Maxlnstructions, 
bp [ i] .Totallnstructions) ; 



} 



return 0; 
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The output produced by Example 1.4 after an internal breakpoint had been set at 
NTOSKRNLlNtCreateProcess was: 

80193206 060 19700 21010 121149 

Therefore, the minimum number of instructions executed by NtCreateProcess was 
19,700, the maximum number was 21,010, and the average number was about 20191. 
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2 

Objects, Object 
Directories, and 
Symbolic Links 



The system services described in this chapter either operate on objects without regard 
to their type or manage the object namespace. 



OBJECT_ATTRIBUTES 



Almost all of the ZwCreateXxx and ZwOpenXxx routines require a pointer to an 
OBJECT_ATTRIBUTES structure as one of their parameters. 

typedef struct _OBJECT_ATTRIBUTES { 

ULONG Length; 

HANDLE RootDirectory ; 

PUNICODE_STRING ObjectName; 

ULONG Attributes; 

PSECURITY_DESCRIPTOR SecurityDescriptor ; 

PSECURITY_QUALITY_OF_SERVICE SecurityQualityOf Service ; 

} OBJ ECT_ATTR I BUTES , * POB J ECT_ATTR I BUTES ; 

Members 

Length 

The size in bytes of the OBJECT_ATTRIBUTES structure. 

RootDirectory 

Optionally specifies a handle to a “container” object. The ObjectName will be inter- 
preted as a name relative to this container. Possible “container” object types include 
Object Directories, File Directories, and Registry Keys. 

ObjectName 

Optionally specifies a name for the object to be created or opened. 
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Attributes 

A bit mask specifying attributes. This member can be zero, or a combination of the 
following flags: 



0BJ_INHERIT 

0BJ_PERMANENT 

0BJ_EXCLUSIVE 

OBJ_CASE_INSENSITIVE 

0BJ_0PENIF 

0BJ_0PENLINK 

OBJ_KERNEL_HANDLE 



0x00000002 

0x00000010 

0x00000020 

0x00000040 

0x00000080 

0x00000100 

0x00000200 



The meanings of the individual flags are discussed in “Remarks.” Depending on the 
type of object to be created or opened, some of the flags are not valid and their 
presence will result in the routine returning STATUS_INVALID_PARAMETER. 



SecurityDescriptor 

Optionally specifies a security descriptor to be applied to the object. Only meaningful 
when creating a new object. 

Secu ri ty Quali ty Of Service 

Optionally specifies a security Quality of Service to be applied to the object. Only 
meaningful when creating new Token or inter-process communication objects (such 
as named pipes). 

Remarks 

The kernel does not maintain information about the current directory of a process. 
(This information is maintained in user mode by ntdll.dll.). Therefore, when the 
Win32 function CreateFile is called to open a file with a relative (to the current 
directory) pathname, the RootDirectory member is used to convey the current direc- 
tory information to the kernel. The Win32 registry functions always create or open 
subkeys of existing key objects; when these functions call the appropriate native system 
service, they store the existing key in the RootDirectory member and the subkey 
name in the ObjectName member. 

The 0BJ_INHERIT flag specifies whether the handle can be inherited. Even if the 
handle can be inherited, whether it is actually inherited depends on the arguments 

to the ZwCreateProcess routine. 

If an object has a name and is created with 0BJ_PERMANENT, it will continue to exist, 
even after the last handle reference to it has been closed. 

SeCreatePermanentPrivilege is needed when specifying OBJ_PERMANENT.To delete a 
permanent object, it is necessary to first obtain a handle to the object and then to 
make the object temporary by calling ZwMakeTemporaryObject. 

Directory and SymbolicLink objects are normally created as permanent objects, but 
other objects such as Sections and Events can also be made permanent. 

(“Permanent” means until next reboot.) 

The 0BJ_EXCLUSIVE flag specifies whether an object is exclusive to one process. If an 
object is created with this flag, the attempts by other processes to access the object (by 
opening it by name or duplicating its handle) will fail with STATUS_ACCESS_DENIED. 
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The OBJ_CASE_INSENSITIVE flag controls how names are compared. If 
OBJ_CASE_INSENSITIVE is set, subsequent name-lookup requests will ignore 
the case of ObjectName rather than performing an exact-match search. 

The 0BJ_0PENIF flag specifies how the ZwCreateXxx routines should behave if an 
object with the specified name already exists. If 0BJ_0PENIF is set, the routines return 
the information status STATUS_OBJECT_NAME_EXISTS and also return a handle to the 
existing object. If 0BJ_0PENIF is clear, the routines return the error status 
STATUS_OBJECT_NAME_COLLISION and do not return a valid handle. 

The OBJ_OPENLINK flag specifies whether the object itself or the object to which it is 
linked should be opened. This flag is normally only used with Registry Keys. For 
example, “\Registry\Machine\Security\Sam” is a registry link to 
“\Registry\Machine\Sam,” and if it is opened with OBJ_OPENLINK then the returned 
handle will refer to “ \Registry\ Machine \ Sam.” These links are distinct from the 
Symbolic Link objects created by ZwCreateSymbolicLinkObject. 

The OBJ_KERNEL_HANDLE flag is only valid in Windows 2000. If a handle to an object is 
created in kernel mode and OBJ_KERNEL_HANDLE is specified, the handle is created in 
the “System” process rather than the current process. 



Z wQ uery Obj e ct 



ZwQueryObject queries generic information about any object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryObject ( 

IN HANDLE Obj ectHandle , 

IN 0BJECT_INF0RMATI0N_CLASS Obj ectlnf ormationClass , 

OUT PVOID Objectlnformation, 

IN ULONG ObjectlnformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ObjectHandle 

A handle to an object. The handle need not grant any specific access. If the informa- 
tion class requested does not return information which is specific to a particular object 
or handle, this parameter may be zero. 

Obj ectlnf ormationClass 

The type of object information to be queried. The permitted values are drawn from 
the enumeration 0BJECT_INF0RMATI0N_CLASS, described in the following section. 

Objectlnformation 

Points to a caller-allocated buffer or variable that receives the requested object 
information. 
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ObjectlnformationLength 

Specifies the size in bytes of Obj ectlnf ormation, that the caller should set according 
to the given Obj ectlnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Obj ectlnf ormation. If Obj ectlnf ormationLength is too small to contain the available 
data, the variable is set to the number of bytes required for the available data. If this 
information is not needed, ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

GetHandlelnformation. 

Remarks 

ZwQueryObject returns generic information about objects. For most object types there 
is a native API routine that returns object type specific information. For example, 
ZwQuerylnf ormationProcess returns information specific to process objects. 



ZwSetlnformationObject 



ZwSetlnformationObject sets attributes on a handle to an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationObject ( 

IN HANDLE Obj ectHandle , 

IN OBJECT_INFORMATION_CLASS Obj ectlnf ormationClass, 

IN PVOID Objectlnformation, 

IN ULONG ObjectlnformationLength 

); 



Parameters 

ObjectHandle 

A handle to an object. The handle need not grant any specific access. 

ObjectlnformationClass 

The type of object information to be set. The permitted values are a subset of the 
enumeration OBJECT_INFORMATION_CLASS, described in the following section. 

Ob j ectlnf orn lation 

Points to a caller-allocated buffer or variable that contains the object information to 
be set. 
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Ob jectlnfont intio n Length 

Specifies the size in bytes of Obj ectlnf ormation, which the caller should set according 
to the given Obj ectlnf ormationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

Set Handlelnf ormation. 

Remarks 

The Win32 function SetHandlelnf ormation exposes the full functionality of 

ZwSetlnformationObject. 



OBJECT_INFORMATION_CLASS 



typedef enum _OBJECT_INFORMATION_CLASS 


i 


Query 


Set 


ObjectBasicInformation, 


// 0 


Y 


N 


Obj ectNamelnf ormation , 


// i 


Y 


N 


Obj ectTypelnf ormation , 


// 2 


Y 


N 


Obj ectAHTypesInf ormation , 


// 3 


Y 


N 


Obj ectHandlelnf ormation 
} OBJECT_INFORMATION_CLASS; 


// 4 


Y 


Y 



ObjectBasicInformation 



typedef struct _OBJECT_BAS I CONFORMATION { // Information Class 0 
ULONG Attributes; 

ACCESS_MASK GrantedAccess ; 

ULONG HandleCount; 

ULONG PointerCount ; 

ULONG PagedPoolUsage; 

ULONG NonPagedPoolUsage; 

ULONG Reserved[3] ; 

ULONG NamelnformationLength; 

ULONG TypelnformationLength; 

ULONG SecurityDescriptorLength; 

LARGE_INTEGER CreateTime; 

} OB JECT_BAS I CONFORMATION, *POBJECT_BASIC_INFORMATION; 

Members 



Attributes 

A bit array of flags that specify properties of the object and the handle referring to it 
that was used in the call to ZwQueryOb ject. Observed values include: 



HANDLE_FLAG_INHERIT 

HANDLE_FLAG_PROTECT_FROM_CLOSE 

PERMANENT 

EXCLUSIVE 



0x01 

0x02 

0x10 



0x20 (different encoding than in 
SYSTEM_OBJ ECT_I N FORMAT I ON ) 
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GrantedAccess 

The access to the object granted when the handle was created. 

HandleCount 

The number of handle references to the object. 

PointerCount 

The number of pointer references to the object. 

PagedPoolUsage 

The amount of paged pool used by the object if different from the default for the 
object type. 

NonPagedPoolUsage 

The amount of nonpaged pool used by the object if different from the default for the 
object type. 

NamelnformationLength 

The size in bytes of the buffer that would be needed to hold the information returned 
by the Obj ectNamelnformation class for the handle if this information is available. For 
object types that manage their own namespace, such as Files and Keys, this value is 
normally zero, meaning just that the value is unknown. 

Type Inform a tionLength 

The size in bytes of the buffer that would theoretically be needed to hold the infor- 
mation returned by the ObjectTypelnformation class for the handle. In practice, if this 
length is not a multiple of four, the required length is the lowest multiple of four that 
is greater than Typelnf ormationLength. 

Secu ri ty Descrip to r Length 

The size in bytes of the buffer that would be needed to hold the information returned 
by a call to ZwQuerySecurityObject for the handle. This information is only available 
if the Obj ectHandle parameter grants READ_CONTROL access, otherwise zero is returned. 

CreateTime 

If the object is a Symbolic Link, the creation time of the object in the standard time 
format (that is, the number of 100-nanosecond intervals since January 1, 1601), other- 
wise zero. 

Remarks 



The code in Example 2.1 uses this information class. 
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ObjectNamelnformation 



typedef struct _OBJECT_NAME_INFORMATION { // Information Class 1 
UNICODE_STRING Name; 

} OBJECT_NAME_INFORMATION , * POB J ECT_NAME_I NFORMAT ION; 

Members 

Name 

The name of the object. 

Remarks 

The Obj ectlnf ormation buffer should be large enough to hold a UNICODE_STRING 
structure and the associated Buffer, which holds the characters of the string. 

If the object to which the handle refers is a file object and the handle was opened 
for synchronous access (by specifying FILE_SYNCHRONOUS_IO_ALERT or FILE_ 
SYNCHRONOUS_IO_NONALERT as CreateOptions), queries of this information class will be 
synchronized with other file operations on the handle. 

The code in Example 2.1 uses this information class. 



ObjectTypelnformation 



typedef struct _OBJECT_TYPE_INFORMATION { // Information Class 2 
UNICODE_STRING Name; 

ULONG ObjectCount; 

ULONG HandleCount; 

ULONG Reservedl [4] ; 

ULONG PeakObjectCount ; 

ULONG PeakHandleCount ; 

ULONG Reserved2[4] ; 

ULONG InvalidAttributes; 

GENERIC_MAPPING GenericMapping ; 

ULONG ValidAccess; 

UCHAR Unknown; 

BOOLEAN MaintainHandleDatabase; 

P00L_TYPE PoolType; 

ULONG PagedPoolUsage; 

ULONG NonPagedPoolUsage; 

} OBJECT_TYPE_INFORMATION , *POBJECT_TYPE_INFORMATION ; 

Members 

Name 

A name that identifies this object type. 

ObjectCount 

The number of objects of this type in the system. 

HandleCount 

The number of handles to objects of this type in the system. 







1996 Ch02 11/19/99 12:25 PM Page 66 



66 Objects, Object Directories, and Symbolic Links: ObjectAIITypesInformation 

PeakObjectCount 

The peak number of objects of this type in the system. 

PeakHandleCount 

The peak number of handles to objects of this type in the system. 

InvalidAttributes 

A bit mask of the 0BJ_Xxx attributes that are not valid for objects of this type. 

GenericMapping 

The mapping ol generic access rights to specific access rights for this object type. 

ValidAccessMask 

The valid specific access rights for this object type. 

Unknown 

Interpretation unknown. Same as SYSTEM_OBJECT_TYPE_INFORMATION . Unknown. 

MaintainHandleDatabase 

Specifies whether the handles to objects of this type should be recorded in the objects 
to which they refer. 

PoolType 

The type of pool from which this object type is allocated (paged or nonpaged). 

PagedPoolUsage 

The amount of paged pool used by objects of this type. 

NonPagedPoolUsage 

The amount of nonpaged pool used by objects of this type. 

Remarks 

The Obj ectlnf emulation buffer should be large enough to hold the Buffer associated 
with the Name UNICODE_STRING. 

This information is similar to that returned by ZwQuerySystemlnf ormation with an 
information class of SystemObj ectlnf ormation (17) . 

The code in Example 2.1 uses this information class. 



ObjectAIITypesInformation 



typedef struct _OBJECT_ALL_TYPES_INFORMATION { // Information Class 3 
ULONG NumberOfTypes; 

OBJECT_TYPE_INFORMATION Typelnf ormation ; 

} OBJECT_ALL_TYPES_INFORMATION , *POBJECT_ALL_TYPES_INFORMATION; 
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Members 

NumberOfTypes 

The number of types known to the object manager. 

Typelnformation 

A sequence of OBJECT_TYPE_INFORMATION structures, one per type. 

Remarks 

The ObjectHandle parameter need not contain a valid handle to query this 
information class. 

The Buffer associated with the type name immediately follows each 
OBJECT_TYPE_INFORMATION structure. The next OBJECT_TYPE_INFORMATION structure 
follows this Buffer, starting on the first four-byte boundary. 

This information is similar to that returned by ZwQuerySystemlnf ormation with an 
information class of SystemObj ectlnf ormation (17). 



ObjectHandlelnformation 



typedef struct _OBJECT_HANDLE_ATTRIBUTE_INFORMATION { // Information Class 4 
BOOLEAN Inherit; 

BOOLEAN ProtectFromClose; 

} OBJECT_HANDLE_ATTRIBUTE_INFORMATION, *POBJECT_HANDLE_ATTRIBUTE_INFORMATION ; 

Members 

Inherit 

Specifies whether the handle should be inherited by child processes. 

ProtectFrom Close 

Specifies whether the handle should be protected from being closed. 

Remarks 

This information class can be both queried and set. 

The Win32 functions GetHandlelnf ormation and SetHandlelnf ormation query and 
set this information. 



ZwDuplicateObject 



ZwDuplicateObject duplicates the handle to an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDuplicateObject ( 

IN HANDLE SourceProcessHandle, 

IN HANDLE SourceHandle , 
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IN HANDLE TargetProcessHandle, 

OUT PHANDLE TargetHandle OPTIONAL, 
IN ACCESS_MASK DesiredAccess , 

IN ULONG Attributes, 

IN ULONG Options 

); 



Parameters 



SourceProcessHandle 

Identifies the process containing the handle to duplicate. The handle must grant 
PROCESS_DUP_HANDLE access. 

SourceHandle 

Identifies the handle to duplicate. The handle need not grant any specific access. 

TargetProcessHandle 

Identifies the process that is to receive the duplicated handle. The handle must grant 
PROCESS_DUP_HANDLE access. 

TargetHandle 

Points to a caller-allocated buffer or variable that receives the value of the duplicate 
handle. If TargetHandle is a null pointer, the handle is duplicated, but its value is not 
returned to the caller. 



DesiredAccess 

Specifies the access requested for the new handle. This parameter is ignored if the 
Options parameter specifies the DUPLICATE_SAME_ACCESS flag. 

Attributes 

Specifies the set of attributes for the new handle. The valid values include 
HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE.This parameter is 
ignored if the Options parameter specifies the DUPLICATE_SAME_ATTRIBUTES flag. 



Options 

Specifies optional actions. This parameter can be zero, or any combination of the 
following flags: 



DUPLICATE_CLOSE_SOURCE 

DUPLICATE_SAME_ACCESS 

DUPLICATE_SAME_ATTRIBUTES 



Closes the source handle. This occurs 
regardless of any error status returned. 
Ignores the DesiredAccess parameter. The 
duplicate handle has the same access as the 
source handle. 

Ignores the Attributes parameter. The 
duplicate handle has the same attributes as 
the source handle. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_ACCESS_DENIED. or STATUS_PROCESS_IS_TERMINATING. 
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Related Win32 Functions 

DuplicateHandle. 

Remarks 

The Win32 function DuplicateHandle exposes the full functionality of 

ZwDuplicateObject. 



ZwMakeTemporaryObject 



ZwMakeTemporaryObject removes the permanent attribute of an object if it was 
present. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwMakeTemporaryObject ( 

IN HANDLE Handle 

); 



Parameters 



Handle 

A handle to an object. The handle need not grant any specific access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_ACCESS_DENIED. 

Related Win32 Functions 

None. 

Remarks 

ZwMakeTemporaryObject is documented in the DDK. 



ZwClose 



ZwClose closes a handle to an object. 

NTSYSAPI 
NTSTATUS 
NTAPI 
ZwClose ( 

IN HANDLE Handle 

); 
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Parameters 

Handle 

A handle to an object. The handle need not grant any specific access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, or 
STATUS_HANDLE_NOT_CLOSABLE. 

Related Win32 Functions 

CloseHandle. 

Remarks 

ZwClose is documented in the DDK. 



Example 2.1: Listing Open Handles of a Process 



#include "ntdll.h" 

#include <stdlib.h> 

#include <stdio.h> 

int main(int argc, char *argv[]) 

{ 

if (argc == 1 ) return 0; 

ULONG pid = strtoul(argv[1 ] , 0, 0); 

EnablePrivilege(SE_DEBUG_NAME) ; 

HANDLE hProcess = OpenProcess(PROCESS_DUP_HANDLE, FALSE, pid); 

ULONG n = 0x1000; 

PULONG p = new UL0NG[ n] ; 

while (NT : :ZwQuerySystemInformation(NT : :SystemHandleInformation, 

p, n * sizeof *p, 0) 

== STATUS_INFO_LENGTH_MISMATCH) 

delete [] p, p = new UL0NG[n *= 2]; 

NT: :PSYSTEM_HANDLE_INFORMATION h = NT: :PSYSTEM_HANDLE_INFORMATION(p + 1); 

for (ULONG i = 0; i < *p; i++) { 

if ( h [ i] .Processld == pid) { 

HANDLE hObject; 

if (NT: :ZwDuplicateObject (hProcess, HANDLE(h[i] .Handle) , 
NtCurrentProcess( ) , &h0bject, 

0, 0, DUPLICATE_SAME_ATTRIBUTES) 

! = STATUS_SUCCESS ) continue; 

NT: : OBJ ECT_BAS I CONFORMATION obi; 
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NT : :ZwQueryObject (hObject , NT : :ObjectBasicInformation, 

&obi, sizeof obi, &n); 

printf ("%p %04hx %61x %2x %31x %31d %41d ", 

h [ i] . Object, h [ i] . Handle, h[i] .GrantedAccess, 
int(h[i] .Flags) , obi. Attributes, 
obi.HandleCount - 1, obi. PointerCount - 2); 

n = obi.TypelnformationLength + 2; 

NT: :POBJECT_TYPE_INFORMATION oti 

= NT: :POBJECT_TYPE_INFORMATION(new CHAR [ n ] ) ; 

NT : :ZwQueryObject ( hObject, NT : :ObjectTypeInformation, 
oti, n, &n); 

printf ("%-14.*ws ", ot i [ 0 ] .Name . Length / 2, ot i [ 0 ] .Name. Buffer) ; 

n = obi.NamelnformationLength == 0 

? MAX_PATH * sizeof (WCHAR) : obi.NamelnformationLength; 

NT: :POBJECT_NAME_INFORMATION oni 

= NT: :POBJECT_NAME_INFORMATION(new CHAR [ n ] ) ; 

NTSTATUS rv = NT: :ZwQueryObject ( hObject, 

NT: :ObjectNameInformation, 
oni, n, &n); 

if (NT_SUCCESS(rv) ) 

printf ("%. *ws" , oni[0] .Name. Length / 2, oni[0] .Name. Buffer) ; 
printf ( " \n" ) ; 

CloseHandle(hObject) ; 

} 

} 

delete [] p; 

CloseHandle(hProcess) ; 
return 0; 



Unlike Example 1.2, Example 2.1 does not require any particular setting of 
NtGlobalFlag. However, it has the drawback of hanging when querying the names 
of pipes that have been opened for synchronous access and that have a pending read or 
write operation. All services have such a handle (used for communication with the 
Service Control Manager). 

When displaying the HandleCount and PointerCount values, Example 1.2 subtracts 
the contribution to the counts arising from its own references to the object. 



ZwQuerySecurityObject 



ZwQuerySecurityObject retrieves a copy of the security descriptor protecting an 
object . 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySecurityObject ( 
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IN HANDLE Handle, 

IN SECURITY_INFORMATION Securitylnf ormation , 
OUT PSECURITY_DESCRIPTOR SecurityDescriptor , 
IN ULONG SecurityDescriptorLength, 

OUT PULONG ReturnLength 

); 



Parameters 

Handle 

A handle to an object. The handle must either grant READ_C0NTR0L access to the object 
or the caller must be the owner of the object. To access the system ACL of the object, 
the handle must grant ACCESS_SYSTEM_SECURITY. 

Security Information 

A bit mask specifying the type of information being requested. The defined values are: 



OWNER_SECURITY_INFORMATION 0x01 
GROUP_SECURITY_INFORMATION 0x02 
DACL_SECURITY_INFORMATION 0x04 
SACL_SECURITY_INFORMATION 0x08 



Secu ri ty Descrip to r 

Points to a caller- allocated buffer or variable that receives the requested security infor- 
mation in the form of a SECURITY_DESCRIPTOR.The SECURITY_DESCRIPTOR structure is 
returned in self-relative format. 

SecurityDescriptorLength 

The size in bytes of SecurityDescriptor. 

ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
SecurityDescriptor. If SecurityDescriptorLength is too small to contain the avail- 
able data, the variable is set to the number of bytes required for the available data. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

Get Ke rnelOb j ect Security, GetUserObj ect Security. 

Remarks 

GetKernelObj ectSecurity and GetUserObj ectSecurity both expose the full 
functionality of ZwQuerySecurityObject. 

SeSecurityPrivilege is needed to open an object for ACCESS_SYSTEM_SECURITY 
access. This privilege need not be enabled at the time of calling 

ZwQuerySecurityObj ect. 
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ZwSetSecurityObject 



ZwSetSecurityObject sets the security descriptor protecting an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetSecurityObject ( 

IN HANDLE Handle, 

IN SECURITY_INFORMATION Securitylnf ormation , 

IN PSECURITY_DESCRIPTOR SecurityDescriptor 

); 



Parameters 



Handle 

A handle to an object. The handle must either grant WRITE_OWNER and/or WRITE_DAC 
access to the object as appropriate, or the caller must be the owner of the object. To 
access the system ACL of the object, the handle must grant ACCESS_SYSTEM_SECURITY. 



Security Information 

A bit mask specifying the type of information being set. The defined values are: 



OWNER_SECURITY_INFORMATION 0x01 
GROUP_SECURITY_INFORMATION 0x02 
DACL_SECURITY_INFORMATION 0x04 
SACL_SECURITY INFORMATION 0x08 



SecurityDescriptor 

Points to a SECURITY_DESCRIPTOR structure containing the new security information. 
The SECURITY DESCRIPTOR structure must be in self-relative format. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

Set Ke rnelOb j ect Security, SetUserObj ect Security. 

Remarks 

SetKernelObj ectSecurity and SetUserObj ectSecurity both expose the full func- 
tionality of ZwSetSecurityObject. 

SeSecurityPrivilege is needed to open an object for ACCESS_SYSTEM_SECURITY 
access. This privilege need not be enabled at the time of calling ZwSetSecurityObject. 



ZwCreateDirectoryObject 



ZwCreateDirectoryObject creates or opens an object directory. 

NTSYSAPI 

NTSTATUS 

NTAPI 
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ZwCreateDirectoryObject ( 

OUT PHANDLE DirectoryHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes 

); 



Parameters 



DirectoryHandle 

Points to a caller-allocated buffer or variable that receives the value of the directory 
object handle if the call is successful. 



DesiredAccess 

The type of access that the caller requires to the directory object. This parameter can 
be zero, or any combination of the following flags: 



DIRECTORY_QUERY 
DIRECTORY_TRAVERSE 
DIRECTORY_CREATE_OBJECT 
DIRECTORY_CREATE_SUBDI RECTORY 
DIRECTORY_ALL_ACCESS 



Query access 

Name lookup access 

Name creation access 

Subdirectory creation access 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Obj ectAttributes 

Points to a structure that specifies the object’s attributes, including the name for the 
new directory object. OBJ_OPENLINK is not a valid attribute for a directory object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_EXISTS, or STATUS_OBJECT_NAME_COLLISION. 

Related Win32 Functions 

None. 

Remarks 

ZwCreateDirectoryObject is documented in the DDK. 



ZwOpenDirectoryObject 



ZwOpenDirectoryObject opens an object directory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenDirectoryObject ( 

OUT PHANDLE DirectoryHandle, 

IN ACCESS_MASK DesiredAccess, 

IN P0BJECT_ATTRIBUTES Obj ectAttributes 

); 





1996 Ch02 11/19/99 12:25 PM Page 75 



Objects, Object Directories, and Symbolic Links: ZwQueryDirectoryObject 



75 



Parameters 



DirectoryHandle 

Points to a caller-allocated buffer or variable that receives the value of the directory 
object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the directory object. This 
parameter can be zero, or any combination of the following flags: 

DIRECTORY_QUERY Query access 

DIRECTORY_TRAVERSE Name lookup access 

DIRECTORY_CREATE_OBJECT Name creation access 

DIRECTORY_CREATE_SUBDIRECTORY Subdirectory creation access 
DIRECTORY_ALL_ACCESS All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Object Attributes 

Points to a structure that specifies the object’s attributes, including the name of the 
directory object. 0BJ_0PENLINK is not a valid attribute for a directory object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwQueryDirectoryObject 



ZwQueryDirectoryObject retrieves information about the contents of an object 
directory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryDirectoryObject ( 

IN HANDLE DirectoryHandle , 

OUT PVOID Buffer, 

IN ULONG BufferLength, 

IN BOOLEAN ReturnSingleEntry , 

IN BOOLEAN RestartScan, 

IN OUT PULONG Context, 

OUT PULONG ReturnLength OPTIONAL 

); 
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Parameters 

DirectoryHandle 

A handle to a directory object. The handle must grant DIRECTORY_QUERY access. 

Buffer 

Points to a caller-allocated buffer or variable that receives the names of entries in the 
directory. 

BufferLength 

Specifies the size in bytes of Buffer. 

Return SingleEntry 

Specifies whether a single entry should be returned; if false, as many entries as will fit 
in the buffer are returned. 

RestartScan 

Specifies whether the scan of the directory should be restarted; if true, the input value 
of the Context parameter is ignored. 



Context 

Points to a caller- allocated buffer or variable that maintains the position of a directory 




ReturnLength 

Optionally points to number of bytes actually returned to Buffer. If this information is 
not needed, ReturnLength may be a null pointer. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_MORE_ENTRIES, STATUS_NO_MORE_ENTR I ES, or STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

QueryDosDevice . 

Remarks 

The information returned to Buffer is an array of DIRECTORY_BASIC_INFORMATION 
structures, terminated by a DIRECTORY_BAS I CONFORMATION structure containing all 
zeroes. The strings pointed to by the UNICODE_STRING members follow this data, and 
the Buffer must be large enough to contain them. 

typedef struct _DIRECTORY_BASIC_INFORMATION { 

UNICODE_STRING ObjectName; 

UNICODE_STRING ObjectTypeName; 

} DIRECTORY_BASIC_INFORMATION, *PDIRECTORY_BASIC_INFORMATION; 

QueryDosDevice can only scan one fixed directory, namely “\??” (ignoring complica- 
tions arising from multi-user support under Windows Terminal Server). This directory 
was formerly named “\DosDevices” and is conventionally used to store symbolic links 
to device objects. 
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ZwCreateSymbolicLinkObject creates or opens a symbolic link object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateSymbolicLinkObject ( 

OUT PHANDLE SymbolicLinkHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN PUNICODE_STRING TargetName 
); 

Parameters 

SymbolicLinkHandle 

Points to a caller- allocated buffer or variable that receives the value of the symbolic 
link object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the symbolic link object. This 
parameter can be zero, or any combination of the following flags: 



Obj ectAttributes 

Points to a structure that specifies the objects attributes, including the name of the 
symbolic link object. 0BJ_0PENLINK is not a valid attribute for a symbolic fink object. 

TargetName 

Specifies the name of the object for which the symbolic link will be an alias. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_EXISTS, or STATUS_OBJECT_NAME_COLLISION. 

Related Win32 Functions 

Def ineDosDevice. 

Remarks 

Def ineDosDevice can only create symbolic links in one fixed directory, namely “\??” 
(ignoring complications arising from multi-user support under Windows Terminal 
Server) . 



SYMBOLIC_LINK_QUERY 

SYMBOLIC_LINK_ALL_ACCESS 



Query access 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 
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ZwOpenSymbolicLinkObject 



ZwOpenSymbolicLinkObject opens a symbolic link object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenSymbolicLinkObject ( 

OUT PHANDLE SymbolicLinkHandle , 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 



Parameters 

SymbolicLinkHandle 

Points to a caller-allocated buffer or variable that receives the value of the symbolic 
link object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the symbolic link object. This 
parameter can be zero, or any combination of the following flags: 

SYMBOLIC_LINK_QUERY Query access 

SYMBOLIC_LINK_ALL_ACCESS All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Obj ectAttributes 

Points to a structure that specifies the object’s attributes, including the name of the 
symbolic link object. 0BJ_0PENLINK is not a valid attribute for a symbolic link object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_OBJECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwQuerySymbolicLinkObject 



ZwQuerySymbolicLinkObject retrieves the name of the target of a symbolic link. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySymbolicLinkObject ( 

IN HANDLE SymbolicLinkHandle, 

IN OUT PUNICODE_STRING TargetName, 

OUT PULONG ReturnLength OPTIONAL 

); 
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Parameters 



SymbolicLinkHandle 

A handle to a symbolic link object. The handle must grant SYMBOLIC_LINK_QUERY 
access. 



TargetName 

Points to a caller- allocated buffer or variable containing an initialised UNICODE_STRING 
with valid Buffer and MaximumLength members. If the call is successful, the Length 
member is updated. 

ReturnLength 

Optionally points to number of bytes actually returned to TargetName . Buff er. If this 
information is not needed, ReturnLength may be a null pointer. This length includes 
the trailing UNICODE null character. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS BUFFER TOO SMALL. 



Related Win32 Functions 

QueryDosDevice. 

Remarks 



QueryDosDevice can only query symbolic links in one fixed directory, namely 
“ \ ??” (ignoring complications arising from multi-user support under Windows 
Terminal Server). 
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Virtual Memory 



The system services described in this chapter manipulate virtual memory. 



ZwAllocateVirtualMemory 



ZwAllocateVirtualMemory allocates virtual memory in the user mode address range. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAllocateVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress, 

IN ULONG ZeroBitS, 

IN OUT PULONG AllocationSize , 

IN ULONG AllocationType, 

IN ULONG Protect 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual memory 
should be allocated. The handle must grant PR0CESS_VM_0PERATI0N access. 

BaseAddress 

Points to a variable that will receive the base address of the allocated virtual memory. 

If the initial value of this variable is not null, the virtual memory is allocated starting at 
the specified address and rounded down to the nearest allocation granularity boundary 
if necessary. 

Zero Bits 

Specifies the number of high-order address bits that must be zero in the base address 
of the virtual memory. The value of this parameter must be less than 21; it is used only 
when the operating system determines where to allocate the virtual memory, such as 
when BaseAddress is null. 
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Allocation Size 

It points to a variable that specifies the size, in bytes, of the virtual memory to allocate, 
and receives the size of virtual memory actually allocated. If BaseAddress is null, this 
value is rounded up to the next page size boundary; otherwise, it is adjusted to the size 
of all the pages that contain one or more bytes in the range from BaseAddress to 
(BaseAddress+AllocationSize). 



AllocationType 

A set of flags that describes the type of allocation to be performed for the specified 
region of pages. The permitted values are selected combinations of the flags: 



MEM_COMMIT 

MEM_RESERVE 

MEM_RESET 

MEM_T0P_D0WN 

MEM_WRITE_WATCH 

MEM_PHYSICAL 



0x001000 Commit memory 

0x002000 Reserve but do not commit memory 

0x080000 Mark data in memory as obsolete 

0x100000 Allocate at highest possible address 

0x200000 Track writes to memory 

0x400000 Create a physical view 



Protect 

Specifies the protection for the pages in the region. Permitted values are drawn from 
the following list, possibly combined with PAGE_GUARD or PAGE_NOCACHE: 

PAGE_NOACCESS 

PAGE_READONLY 

PAG E_R E ADWR I TE 

PAGE_EXECUTE 

PAGE_EXECUTE_READ 

PAGE_EXECUTE_READWRITE 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NO_MEMORY, STATUS_ 
CONFLICTING_ADDRESSES, STATUS_ALREADY_COMMITTED, STATUS_INVALID_PAGE_ 
PROTECTION, or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

VirtualAlloc, VirtualAllocEx. 

Remarks 

VirtualAllocEx exposes almost all of the functionality of ZwAllocateVirtualMemory. 

To commit virtual memory, it must either first be reserved, or both MEM_COMMIT and 
MEM_RESERVE must be specified as the AllocationType (optionally combined with 
MEM_TOP_DOWN). 

The flag MEM_RESET is documented in the Knowledge Base article Q162104 and in 
newer versions of the Platform SDK. 

The flag MEM_WRITE_WATCH is only valid in Windows 2000. If the system does not 
support write watching and this flag is specified, ZwAllocateVirtualMemory fails with 
status STATUS NOT SUPPORTED. 
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The flag MEM_PHYSICAL is only valid in Windows 2000; it can only and must be com- 
bined with the flag MEM_RESERVE. It reserves a range of virtual addresses to be used to 
map views of physical memory allocated with ZwAllocateUserPhysicalPages. 



ZwFreeVirtualMemory 



ZwFreeVirtualMemory frees virtual memory in the user mode address range. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFreeVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress , 

IN OUT PULONG FreeSize, 

IN ULONG FreeType 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process from which the virtual memory 
should be freed. The handle must grant PR0CESS_VM_0PERATI0N access. 

BaseAddress 

Points to a variable that specifies the base address of the virtual memory to be freed. 

FreeSize 

Points to a variable that specifies the size, in bytes, of the virtual memory to free and 
receives the size of virtual memory actually freed. If FreeType is MEM_RELEASE, this 
value must be zero. 

FreeType 

A set of flags that describes the type of de-allocation to be performed for the specified 
region of pages. The permitted values are: 

MEM_DEC0MMIT Decommit but maintain reservation 

MEM_RELEASE Decommit and free reservation 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_UNABLE_TO_FREE_VM, 
STATUS_UNABLE_TO_DELETE_SECTION, STATUS_FREE_VM_NOT_AT_BASE, 
STATUS_MEMORY_NOT_ALLOCATED, or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

VirtualFree, VirtualFreeEx. 

Remarks 

VirtualFreeEx exposes almost all of the functionality of ZwFreeVirtualMemory. 
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ZwQueryVirtualMemory 



ZwQueryVirtualMemory retrieves information about virtual memory in the user mode 
address range. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryVirtualMemory ( 

IN HANDLE ProcessHandle, 

IN PVOID BaseAddress, 

IN MEMORY_INFORMATION_CLASS Memory Inf ormationClass, 

OUT PVOID Memorylnformation, 

IN ULONG MemorylnformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process whose virtual memory informa- 
tion is queried. The handle must grant PROCESS_QUERY_INFORMATION access. 

BaseAddress 

The base address ot the region of pages to be queried. This value is rounded down to 
the next page boundary. It the information class requested does not return information 
that is specific to a particular address, this parameter may be zero. 

MemorylnformationClass 

The type of virtual memory information to be queried. The permitted values are 
drawn from the enumeration MEMORY_INFORMATION_CLASS, described in the following 
section. 

Memorylnformation 

Points to a caller-allocated buffer or variable that receives the requested virtual 
memory information. 

MemorylnformationLength 

Specifies the size in bytes of Memorylnformation, which the caller should set according 
to the given Memorylnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Memorylnformation if the call was successful. It this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_INFO_CLASS, 
STATUS_INFO_LENGTH_MISMATCH. STATUS_INVALID_ADDRESS, STATUS_FILE_INVALID, or 
STATUS PROCESS IS TERMINATING. 
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Related Win32 Functions 

VirtualQuery, VirtualQueryEx. 

Remarks 

None. 



MEMORY_INFORMATION_CLASS 



typedef enum _MEMORY_INFORMATION_CLASS { 
MemoryBasicInformation , 
MemoryWorkingSetList , 
MemorySectionName , 
MemoryBasicVlmlnformation 
} MEMORY_INFORMATION_CLASS; 



MemoryBasicInformation 



typedef struct _MEMORY_BASIC_INFORMATION { // Information Class 0 
PVOID BaseAddress; 

PVOID AllocationBase; 

ULONG AllocationProtect ; 

ULONG RegionSize; 

ULONG State; 

ULONG Protect; 

ULONG Type; 

} MEMORY_BAS I CONFORMATION, *PMEMORY_BASIC_INFORMATION ; 

Members 

BaseAddress 

The virtual base address of the region of pages. 



AllocationBase 

The virtual base address of the initial allocation region that contains this region. 



AllocationProtect 

The access protection of the pages specified when the region was initially allocated. 
Possible values are drawn from the following list, possibly combined with PAGE_GUARD 
or PAGE_NOCACHE: 

PAGE_NOACCESS 

PAGE_READONLY 

PAG E_R E ADWR I TE 

PAGE_EXECUTE 

PAGE_EXECUTE_READ 

PAGE_EXECUTE_READWRITE 



RegionSize 

The size, in bytes, of the region beginning at the base address in which all pages 
belong to the same initial allocation region and have identical protection and state 
attributes. 
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State 

The state of the pages in the region. Possible values include: 

MEM_COMMIT Memory is reserved and committed 

MEM_RESERVE Memory is reserved but not committed 

MEM_FREE Memory is free 



Protect 

The current access protection of the pages in the region. 

Type 

The type of the pages in the region. Possible values include zero if the state is 
MEM_FREE, or: 

MEM_PRIVATE Memory is private 

MEM_MAPPED Memory is shareable and mapped from a data section 

MEM_IMAGE Memory is shareable and mapped from an image section 

Remarks 

MEMORY_BASIC_INFORMATION is identical to the structure of the same name returned by 
the Win32 function VirtualQueryEx. 



Memory WorkingSetList 



typedef struct _MEMORY_WORKING_SET_LIST { // Information Class 1 
ULONG NumberOf Pages; 

ULONG WorkingSetList [ 1 ] ; 

} MEMORY_WORKING_SET_LIST, *PMEMORY_WORKING_SET_LIST; 

Members 

NumberOfPages 

The number of pages in the working set list. 



WorkingSetList 

An array of working set list entries. The high 20 bits of an entry represent the high 20 
bits of the virtual address of the working set list entry, and the low 1 2 bits are a bit 
array of flags. The following flag interpretations are defined: 



WSLE_PAGE_READONLY 0x001 
WSLE_PAGE_EXECUTE 0x002 
WS L E_P AG E_R E ADWR I T E 0x004 
WSLE_PAGE_EXECUTE_READ 0x003 
WSLE_PAGE_WRITECOPY 0x005 
WSLE_PAGE_EXECUTE_READWRITE 0x006 
WSLE_PAGE_EXECUTE_WRITECOPY 0x007 
WSLE_PAGE_SHARE_COUNT_MASK 0X0E0 
WSLEPAGE SHAREABLE 0x100 



// Page is read only 
// Page is executable 
// Page is writeable 

// Page should be copied on write 

// Page should be copied on write 

// Page is shareable 



Remarks 

ZwQueryVirtualMemory with an information class ot MemoryWorkingSetList always 
returns STATUS_SUCCESS. To test for success, verify that Memorylnf ormationLength is 
greater than the ReturnLength. 
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Flag bits that are not defined are neither set nor cleared, and so it is advisable to zero 
the Memorylnf ormation buffer before calling ZwQueryVirtualMemory. 

An indication of whether a page is locked (in memory or in the working set) is not 
returned although this information is stored in the working set list of the process. 

The PSAPI function QueryWorkingSet uses this information class. 

The share count for shareable pages is only available in Windows 2000. A share count 
of seven means that at least seven processes are sharing the page. 



MemorySectionName 



typedef struct _MEM0RY_SECTI0N_NAME { // Information Class 2 
UNICODE_STRING SectionFileName ; 

} MEM0RY_SECTI0N_NAME , *PMEM0RY_SECTI0N_NAME; 

Members 



SectionFileName 

The name of the file backing the section. 



Remarks 



The BaseAddress parameter must point to the base address of a mapped data section; 
the name of the file backing an image section is not returned (this seems to be an 
arbitrary restriction in the implementation of ZwQueryVirtualMemory). 



Memorylnf ormationLength must be large enough to accommodate the 
UNICODE_STRING structure and the actual Unicode string name itself. 



The PSAPI function GetMappedFileName uses this information class. 



ZwLockVirtualMemory 



ZwLockVirtualMemory locks virtual memory in the user mode address range, ensuring 
that subsequent accesses to the locked region of virtual memory will not incur page 
faults. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwLockVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress , 

IN OUT PULONG LockSize, 

IN ULONG LockType 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual memory 
should be locked. The handle must grant PR0CESS_VM_0PERATI0N access. 
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BaseAddress 

Points to a variable that specifies the base address of the virtual memory to be locked, 
and receives the base address of the virtual memory actually locked. 

LockSize 

Points to a variable that specifies the size, in bytes, of the virtual memory to lock, and 
receives the size of virtual memory actually locked. 

LockType 

A set of flags that describes the type of locking to be performed for the specified 
region of pages. The permitted values are combinations of the flags: 

LOCK_VM_IN_WSL 0x01 // Lock page in working set list 

LOCK_VM_IN_RAM 0x02 // Lock page in physical memory 

Return Value 

Returns STATUS_SUCCESS, STATUS_WAS_LOCKED or an error status, such as 
STATUS_PRIVILEGE_NOT_HELD, STATUS_WORKING_SET_QUOTA, or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

VirtualLock. 

Remarks 

SeLockMemoryPrivilege is required to lock pages in physical memory. 

All of the pages that contain one or more bytes in the range from BaseAddress to 
(BaseAddress+LockSize) are locked. 



ZwUnlockVirtualMemory 



ZwUnlockVirtualMemory unlocks virtual memory in the user mode address range. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwUnlockVirtualMemory ( 

IN HANDLE ProcessHandle, 

IN OUT PVOID *BaseAddress , 

IN OUT PULONG LockSize, 

IN ULONG LockType 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual memory 
should be unlocked. The handle must grant PROCESS_VM_OPERATION access. 
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BaseAddress 

Points to a variable that specifies the base address of the virtual memory to be 
unlocked, and receives the size of virtual memory actually unlocked. 

LockSize 

Points to a variable that specifies the size, in bytes, of the virtual memory to unlock, 
and receives the size of virtual memory actually unlocked. 

LockType 

A set of flags that describes the type of unlocking to be performed for the specified 
region of pages. The permitted values are combinations of the flags: 

LOCK_VM_IN_WSL 0x01 // Unlock page from working set list 

LOCK_VM_IN_RAM 0x02 // Unlock page from physical memory 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_NOT_LOCKED, or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

VirtualUnlock. 



Remarks 

SeLockMemoryPrivilege is required to unlock pages from physical memory. 



All of the pages that contain one or more bytes in the range from BaseAddress to 
(BaseAddress+LockSize) are unlocked. They must all have been previously locked. 



ZwReadVirtualMemory 



ZwReadVirtualMemory reads virtual memory in the user mode address range of 
another process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReadVirtualMemory ( 

IN HANDLE ProcessHandle, 

IN PVOID BaseAddress, 

OUT PVOID Buffer, 

IN ULONG BufferLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process from which the virtual memory 
should be read. The handle must grant PROCESS_VM_READ access. 
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BaseAddress 

The base address of the virtual memory to read. 

Buffer 

Points to a caller- allocated buffer or variable that receives the contents of the virtual 
memory. 

BufferLength 

Specifies the size in bytes of Buffer and the number of bytes of virtual memory to 
read. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Buffer if the call was successful. If this information is not needed, ReturnLength may 
be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_VI0LATI0N or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

ReadProcessMemory. 

Remarks 

ReadProcessMemory exposes the full functionality of ZwReadVirtualMemory. 



ZwWriteVirtualMemory 



ZwWriteVirtualMemory writes virtual memory in the user mode address range of 
another process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWriteVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN PVOID BaseAddress, 

IN PVOID Buffer, 

IN ULONG BufferLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process to which the virtual memory 
should be written. The handle must grant PROCESS_VM_WRITE access. 

BaseAddress 

The base address oi the virtual memory to write. 
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Buffer 

Points to a caller- allocated buffer or variable that specifies the contents of the virtual 
memory. 

BufferLength 

Specifies the size in bytes of Buffer and the number of bytes of virtual memory to 
write. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually read from 
Buffer if the call was successful. If this information is not needed, ReturnLength may 
be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_VIOLATION or 
STATUS_PROCESS_IS_TERMINATING . 

Related Win32 Functions 

WriteProcessMemory. 

Remarks 

WriteProcessMemory exposes the full functionality of ZwWriteVirtualMemory. 
WriteProcessMemory tries to modify the protection on the virtual memory to ensure 
that write access is granted and flushes the instruction cache after the write (by calling 

ZwFlushlnstructionCache). 



ZwProtectVirtualMemory 



ZwProtectVirtuallVIemory changes the protection on virtual memory in the user mode 
address range. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwProtectVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress, 

IN OUT PULONG ProtectSize, 

IN ULONG NewProtect , 

OUT PULONG OldProtect 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual memory 
protection is to be changed. The handle must grant PR0CESS_VM_0PERATI0N access. 
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BaseAddress 

Points to a variable that specifies the base address of the virtual memory to protect, 
and receives the size of virtual memory actually protected. 



Protect Size 

Points to a variable that specifies the size, in bytes, of the virtual memory to protect, 
and receives the size of virtual memory actually protected. 



New Protect 

The new access protection. Permitted values are drawn from the following list, possibly 
combined with PAGE_GUARD or PAGE_NOCACHE. 

PAGE_NOACCESS 

PAGE_READONLY 

PAG E_R E ADWR I TE 

PAGE_WRITECOPY 

PAGE_EXECUTE 

PAGE_EXECUTE_READ 

PAGE_EXECUTE_READWRITE 

PAGE_EXECUTE_WR ITECOPY 



Old Protect 

Points to a variable that receives the previous access protection of the first page in the 
specified region of pages. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NOT_COMMITTED or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

VirtualProtect, VirtualProtectEx. 

Remarks 

VirtualProtectEx exposes almost all of the functionality of 

ZwProtectVirtualMemory. 



ZwFlushVirtualMemory 



ZwFlushVirtualMemory flushes virtual memory in the user mode address range that is 
mapped to a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFlushVirtualMemory ( 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress, 

IN OUT PULONG FlushSize, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk 

); 
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Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual memory 
should be flushed. The handle must grant PR0CESS_VM_0PERATI0N access. 

BaseAddress 

Points to a variable that specifies the base address of the virtual memory to flush, and 
receives the size of virtual memory actually flushed. The address should refer to a 
region backed by a file data section. 

Flush Size 

Points to a variable that specifies the size, in bytes, of the virtual memory to flush, and 
receives the size of virtual memory actually flushed. If the initial value of FlushSize is 
zero, the virtual memory is flushed from the BaseAddress to the end of the section. 

loStatusBlock 

Points to a variable that receives the status of the 1/ O operation (if any) needed to 
flush the virtual memory to its backing file. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NOT_MAPPED_DATA or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

FlushViewOf File. 

Remarks 

None. 



ZwAllocateUserPhysicalPages 



ZwAllocateUserPhysicalPages allocates pages of physical memory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAllocateUserPhysicalPages ( 

IN HANDLE ProcessHandle, 

IN PULONG NumberOf Pages, 

OUT PULONG PageFrameNumbers 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the pages of physical 
memory should be allocated. The handle must grant PROCESS_VM_OPERATION access. 
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NumberOfPages 

Points to a variable that specifies the number of pages of physical memory to allocate. 

PageFrameNumbers 

Points to a caller-allocated buffer or variable that receives the page frame numbers of 
the allocated pages. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

AllocateUserPhysicalPages. 

Remarks 

SeLockMemoryPrivilege is required to allocate pages of physical memory. 

AllocateUserPhysicalPages exposes the full functionality of 

ZwAllocateUserPhysicalPages. 

AllocateUserPhysicalPages is part of the “Address Windowing Extensions” (AWE) 
API, which allows applications to use up to 64GB of physical non-paged memory in a 
32-bit virtual address space. On the Intel platform, the Physical Address Extension 
(PAE) flag in the CR4 register is set (at boot time) to enable 36-bit physical addressing 
if the system has more than 4GB of physical memory. 

The routine ZwAllocateUserPhysicalPages is only present in Windows 2000. 



ZwFreeUserPhysicalPages 



ZwFreeUserPhysicalPages frees pages of physical memory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFreeUserPhysicalPages ( 

IN HANDLE ProcessHandle, 

IN OUT PULONG NumberOfPages, 

IN PULONG PageFrameNumbers 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the pages of physical 
memory should be freed. The handle must grant PR0CESS_VM_0PERATI0N access. 

NumberOfPages 

Points to a variable that specifies the number of pages of physical memory to free, and 
receives the number of pages actually freed. 
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PageFrameNumbers 

Points to a caller-allocated buffer or variable that contains the page frame numbers of 
the pages to be freed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_CONFLICTING_ADDRESSES 
or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

FreeUserPhysicalPages. 

Remarks 

FreeUserPhysicalPages exposes the full functionality of ZwFreeUserPhysicalPages. 
The routine ZwFreeUserPhysicalPages is only present in Windows 2000. 



ZwMapUser Physic alPage s 



ZwMapUserPhysicalPages maps pages of physical memory into a physical memory 
view. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwMapUserPhysicalPages ( 

IN PVOID BaseAddress, 

IN PULONG NumberOf Pages, 

IN PULONG PageFrameNumbers 

); 



Parameters 

BaseAddress 

The address within a physical memory view at which to map the physical mem- 
ory. The address is rounded down to the nearest page boundary if necessary. A physical 
memory view is created by calling ZwAllocateVirtualMemory with an 
AllocationType of MEM_PHYSICAL j MEM_RESERVE. 

Nu mberOfPages 

Points to a variable that specifies the number of pages of physical memory to map. 

PageFrameNum bers 

Points to a caller-allocated buffer or variable that contains the page frame numbers of 
the pages to be mapped. If PageFrameNumbers is a null pointer, the physical memory 
mapped at BaseAddresses is unmapped. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_CONFLICTING_ADDRESSES 
or STATUS PROCESS IS TERMINATING. 
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Related Win32 Functions 

MapUserPhysicalPages. 

Remarks 

MapUserPhysicalPages exposes the full functionality of ZwMapUserPhysicalPages. 
The routine ZwMapUserPhysicalPages is only present in Windows 2000. 

The physical pages must have been previously allocated by 

ZwAllocateUserPhysicalPages. 

For unknown reasons, ZwMapUserPhysicalPages does not provide for specifying the 
process for which the mapping is to be performed; this is in contrast to all the other 
related routines, which do allow a process to be specified. 



ZwMapUserPhysicalPagesScatter 



ZwMapUserPhysicalPagesScatter maps pages of physical memory into a physical mem- 
ory view. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwMapUserPhysicalPagesScatter ( 

IN PVOID *BaseAddresses, 

IN PULONG NumberOf Pages, 

IN PULONG PageFrameNumbers 

); 



Parameters 

BaseAddress 

Points to a caller- allocated buffer or variable that contains an array of the virtual 
addresses (within a physical memory view) at which to map the physical memory. 
The virtual addresses are rounded down to the nearest page boundary if necessary. 

A physical memory view is created by calling ZwAllocateVirtualMemory with an 
AllocationType of MEM_PHYSICAL j MEM_RESERVE. 

Num berOfPages 

Points to a variable that specifies the number of pages of physical memory to map. 

PageFrameNumbers 

Points to a caller-allocated buffer or variable that contains the page frame numbers of 
the pages to be mapped. If PageFrameNumbers is a null pointer, the physical memory 
mapped at BaseAddresses is unmapped. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_CONFLICTING_ADDRESSES 
or STATUS PROCESS IS TERMINATING. 





1996 Ch03 11/19/99 12:25 PM Page 97 



Virtual Memory: ZwGetWriteWatch 



97 



Related Win32 Functions 

MapUserPhysicalPagesScatter. 

Remarks 

MapUserPhysicalPagesScatter exposes the full functionality of 

ZwMapUserPhysicalPagesScatter. 

The routine ZwMapUserPhysicalPagesScatter is only present in Windows 2000. 

The physical pages must have been previously allocated by 

ZwAllocateUserPhysicalPages. 



ZwGetWriteWatch 



ZwGetWriteWatch retrieves the addresses of pages that have been written to in a region 
of virtual memory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwGetWriteWatch ( 

IN HANDLE ProcessHandle , 

IN ULONG Flags, 

IN PVOID BaseAddress, 

IN ULONG RegionSize, 

OUT PULONG Buffer, 

IN OUT PULONG Buff erEntries, 

OUT PULONG Granularity 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process from which the virtual memory 
write watch information should be retrieved. The handle must grant 
PR0CESS_VM_0PERATI0N access. 

Flags 

A bit array of flags. The defined values include: 

WRITE_WATCH_RESET_FLAG 0x01 // Reset the write watch information 

BaseAddress 

The base address of the region of memory for which the write watch information is 
to be retrieved. 

RegionSize 

The size, in bytes, of the region of memory for which the write watch information is 
to be retrieved. 
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Buffer 

Points to a caller- allocated buffer or variable that receives an array of page addresses in 
the region of memory that have been written to since the region was allocated or the 
write watch information was reset. 

BufferEntries 

Points to a variable that specifies the maximum number of page addresses to return 
and receives the actual number of page addresses returned. 

Granularity 

Points to a variable that receives the granularity, in bytes, of the write detection. This is 
normally the size of a physical page. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PROCESS_IS_TERMINATING, 
STATUS_INVALID_PARAMETER_1 , STATUS_I N VAL I D_PARAMETE R_2 , 
STATUS_INVALID_PARAMETER_3, or STATUS_INVALID_PARAMETER_5. 

Related Win32 Functions 

GetWriteWatch. 

Remarks 

GetWriteWatch most of the functionality of ZwGetWriteWatch. 

The routine ZwGetWriteWatch is only present in Windows 2000. 



ZwResetWrite Watch 



ZwResetWriteWatch resets the virtual memory write watch information for a region of 
virtual memory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwResetWriteWatch ( 

IN HANDLE ProcessHandle, 

IN PVOID BaseAddress, 

IN ULONG RegionSize 

); 



Parameters 

ProcessHandle 

A handle of a process object, representing the process for which the virtual 
memory write watch information should be reset. The handle must grant 
PR0CESS_VM_0PERATI0N access. 

BaseAddress 

The base address of the region of memory for which the write watch information is 
to be reset. 
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RegionSize 

The size, in bytes, ot the region of memory for which the write watch information is 
to be reset. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as 
STATUS_PROCESS_IS_TERMINATING, STATUS_INVALID_PARAMETER_1 , 
STATUS_INVALID_PARAMETER_2, or STATUS_INVALID_PARAMETER_3 

Related Win32 Functions 

ResetWriteWatch. 

Remarks 

ResetWriteWatch most of the functionality of ZwResetWriteWatch. 

The routine ZwResetWriteWatch is only present in Windows 2000. 
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Sections 



The system services described in this chapter create and manipulate section objects. 
Section objects are objects that can be mapped into the virtual address space of a process. 
The Win32 API refers to section objects as file-mapping objects. 



ZwCreateSection 



ZwCreateSection creates a section object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateSection ( 

OUT PHANDLE SectionHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 
IN PLARGE_INTEGER SectionSize OPTIONAL, 
IN ULONG Protect, 

IN ULONG Attributes, 

IN HANDLE FileHandle 

); 



Parameters 

Section-Handle 

Points to a variable that will receive the section object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the section object. This parame- 
ter can be zero, or any combination of the following flags: 



SECTI0N_QUERY 

SECTION_MAP_WRITE 

SECTION_MAP_READ 

SECTION_MAP_EXECUTE 

SECTION_EXTEND_SIZE 

SECTION_ALL_ACCESS 



Query access 

Can be written when mapped 

Can be read when mapped 

Can be executed when mapped 

Extend access 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 
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Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a section object. 

SectionSize 

Optionally points to a variable that specifies the size, in bytes, of the section. If 
FileHandle is zero, the size must be specified; otherwise, it can be defaulted from the 
size of the file referred to by FileHandle. 



Protect 

The protection desired for the pages of the section when the section is mapped. 
This parameter can take one of the following values: 

PAGE_READ0NLY 

PAG E_R E ADWR I TE 

PAGE_WRITECOPY 

PAGE_EXECUTE 

PAGE_EXECUTE_READ 

PAGE_EXECUTE_READWRITE 

PAGE_EXECUTE_WRITECOPY 



Attributes 

The attributes for the section. This parameter be a combination of the following 
values: 



SEC_BASED 

SEC_N0_CHANGE 

SEC_IMAGE 

SEC_VLM 

SEC_RESERVE 

SEC_C0MMIT 

SEC_N0CACHE 



0x00200000 // Map section at same address in each process 

0x00400000 // Disable changes to protection of pages 

0x01000000 // Map section as an image 

0x02000000 // Map section in VLM region 

0x04000000 // Reserve without allocating pagefile storage 

0x08000000 // Commit pages; the default behavior 

0x10000000 // Mark pages as non-cacheable 



FileHandle 

Identifies the file from which to create the section object. The file must be opened 
with an access mode compatible with the protection flags specified by the Protect 
parameter. If FileHandle is zero, the function creates a section object of the specified 
size backed by the paging file rather than by a named file in the file system. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_FILE_FOR_SECTION, STATUS_FILE_LOCK_CONFLICT, 
STATUS_MAPPED_FILE_SIZE_ZERO, STATUS_INVALID_PAGE_PROTECTION, 
STATUS_INVALID_IMAGE_FORMAT, STATUS_INCOMPATIBLE_FILE_MAP, 
STATUS_OBJECT_NAME_EXISTS, or STATUS_0BJECT_NAME_C0LLISI0N. 

Related Win32 Functions 



CreateFileMapping. 
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Remarks 

CreateFileMapping exposes almost all of the functionality of ZwCreateSection.The 
main missing features are the ability to specify the attributes SEC_BASED and 
SEC_N0_CHANGE, and the access SECTION_EXTEND. It is also not possible to specify the 
access SECTION_EXECUTE and the related PAGE_EXECUTE_Xxx protections. 

SEC_VLM is only valid in Windows 2000 and is not implemented on the Intel platform. 



ZwOpenSection 



ZwOpenSection opens a section object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenSection ( 

OUT PHANDLE SectionHandle , 

IN ACCESS_MASK DesiredAccess , 

IN P0BJECT_ATTRIBUTES Obj ectAttributes 

); 



Parameters 

SectionHandle 

Points to a variable that will receive the section object handle if the call is successful. 



DesiredAccess 

The type of access that the caller requires to the section object. This parameter can be 
zero, or any combination of the following flags: 



SECTI0N_QUERY 
SECTI0N_MAP_WRITE 
S ECT 1 0N_MAP_R E AD 
SECTI0N_MAP_EXECUTE 
SECTI0N_EXTEND_SIZE 
SECTI0N_ALL ACCESS 



Query access 

Can be written when mapped 
Can be read when mapped 
Can be executed when mapped 
Extend access 
All of the preceding + 
STANDARD_RIGHTS REQUIRED 



Obj ectAttributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a section object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_0BJ ECT_NAME_N0T_F0UND. 

Related Win32 Functions 

OpenFileMapping. 

Remarks 



ZwOpenSection is documented in the DDK. 
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The DDK does not define all the access types listed above. 

OpenFileMapping exposes almost all of the functionality of ZwOpenSection. 

In addition to opening sections created by ZwCreateSection, ZwOpenSection can also 
open the section named “\ Device \PhysicalMemory,” which is backed by the physical 
memory of the system. 



ZwQuerySection 



ZwQuerySection retrieves information about a section object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySection ( 

IN HANDLE SectionHandle, 

IN SECTI0N_INF0RMATI0N_CLASS Sectionlnf ormationClass , 
OUT PVOID Sectionlnf ormation, 

IN ULONG Sectionlnf ormationLength, 

OUT PULONG ResultLength OPTIONAL 

); 



Parameters 

SectionHandle 

A handle to a section object. The handle must grant SECTI0N_QUERY access. 

Sectionlnf ormation Class 

Specifies the type of section object information to be queried. The permitted values 
are drawn from the enumeration SECTI0N_INF0RMATI0N_CLASS, described in the 
following section. 

Sectionlnjormation 

Points to a caller-allocated buffer or variable that receives the requested section object 
information. 

Sectionlnf ormationLength 

Specifies the size in bytes of Sectionlnf ormation, which the caller should set accord- 
ing to the given Sectionlnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Sectionlnf ormation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, 
STATUS_INFO_LENGTH_MISMATCH. or STATUS_SECTION_NOT_IMAGE. 
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Related Win32 Functions 

None. 



Remarks 

None. 



SECTION_INFORMATION_CLASS 



typedef enum _SECTI0N_INF0RMATI0N_CLASS { 
SeetionBasicInformation, 

Sect ionlmagelnformat ion 
} SECTI0N_INF0RMATI0N_CLASS; 



SeetionBasicInformation 



typedef struct _SECTI0N_BASIC_INF0RMATI0N { // Information Class 0 
PVOID BaseAddress; 

ULONG Attributes; 

LARGE_INTEGER Size; 

} SECTI0N_BASIC_INF0RMATI0N , *PSECTI0N_BASIC_INF0RMATI0N; 

Members 

BaseAddress 

If the section is a based section, BaseAddress contains the base address of the 
section; otherwise, it contains zero. 



Attributes 

A bit array of flags that specify properties of the section object. The possible flags are: 



SEC_BASED 

SEC_N0_CHANGE 

SEC_FILE 

SEC_IMAGE 

SEC_VLM 

SEC_RESERVE 

SEC_C0MMIT 

SEC_N0CACHE 



0x00200000 // Section should be mapped at same address in each 
process 

0x00400000 // Changes to protection of section pages are 
disabled 

0x00800000 // Section is backed by a file 

0x01000000 // Section is mapped as an image 

0x02000000 // Section maps VLM 

0x04000000 // Section pages are reserved 

0x08000000 // Section pages are committed 

0x10000000 // Section pages are non-cacheable 



Size 

The size in bytes of the section. 



Remarks 

None. 
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Sectionlmagelnformation 



typedef struct _SECTI0N_IMAGE_INF0RMATI0N { // Information Class 1 
PVOID EntryPoint; 

ULONG Unknownl ; 

ULONG StackReserve; 

ULONG StackCommit; 

ULONG Subsystem; 

USHORT MinorSubsystemVersion; 

USHORT MajorSubsystemVersion; 

ULONG Unknown2; 

ULONG Characteristics; 

USHORT ImageNumber; 

BOOLEAN Executable; 

UCHAR Unknown3 ; 

ULONG Unknown4[3] ; 

} SECTION_IMAGE_INFORMATION , *PSECTION_IMAGE_INFORMATION; 

Members 

EntryPoint 

The entry point of the image. 

Unknownl 

Normally contains zero; interpretation unknown. 

StackReserve 

The default amount of stack to reserve when creating the initial thread to execute 
this image section. The value is copied from the image header (IMAGE_0PTI0NAL_ 
HEADER. SizeOf StackReserve). 

StackCommit 

The default amount of stack to commit when creating the initial thread to execute 
this image section. The value is copied from the image header (IMAGE_0PTI0NAL_ 
HEADER .SizeOf StackCommit). 

Subsystem 

The subsystem under which the process created from this image section should run. 
The value is copied from the image header (IMAGE_0PTI0NAL_HEADER. Subsystem). 

MinorSubsystem Version 

The minor version number of the subsystem for which the image was built. The value 
is copied from the image header (IMAGE_0PTI0NAL_HEADER . MinorSubsystemVersion). 

MajorSubsystem Version 

The major version number of the subsystem for which the image was built. The value 
is copied from the image header (IMAGE_0PTI0NAL_HEADER . MinorSubsystemVersion). 

Unknoivn2 

Normally contains zero; interpretation unknown. 
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Characteristics 

A bit array of flags that specify properties of the image file. The value is copied from 
the image header (IMAGE_FILE_HEADER . Characteristics). 

ImageNumber 

The type of target machine on which the image will run. The value is copied from the 
image header (IMAGE_FILE_HEADER. Machine). 

Executable 

A boolean indicating whether the image file contains any executable code. The value is 
derived from the image header (IMAGE_0PTI0NAL_HEADER . SizeOf Code != 0). 

Unknown3 

Normally contains zero; interpretation unknown. 

Unknown 4 

Normally contains zero; interpretation unknown. 

Remarks 

The information class Sectionlmagelnf ormation is vahd only for image sections 
(sections for which SEC_IMAGE was specified as an attribute to ZwCreateSection). 



ZwExtendSection 



ZwExtendSection extends a file backed data section. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwExtendSection( 

IN HANDLE SectionHandle, 

IN PLARGE_INTEGER SectionSize 

); 

Parameters 

SectionHandle 

A handle to a section object. The handle must grant SECTION_EXTEND_SIZE access. 

SectionSize 

Points to a variable that contains the new size, in bytes, of the section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_ACCESS_DENIED, or STATUS_SECTION_NOT_EXTENDED. 

Related Win32 Functions 



None. 
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Remarks 

ZwExtendSection only extends data sections backed by a file. 



ZwMapViewOfSection 



ZwMapViewOfSection maps a view of a section to a range of virtual addresses. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwMapViewOfSection ( 

IN HANDLE SectionHandle , 

IN HANDLE ProcessHandle , 

IN OUT PVOID *BaseAddress, 

IN ULONG ZeroBitS, 

IN ULONG CommitSize, 

IN OUT PLARGE_INTEGER SectionOf f set OPTIONAL, 

IN OUT PULONG ViewSize, 

IN SECTION_INHERIT InheritDisposition , 

IN ULONG AllocationType, 

IN ULONG Protect 

); 



Parameters 

SectionHandle 

A handle to the section object that is to be mapped. The handle must grant access 
compatible with the Protect parameter, which specifies the protection on the pages 
that map the section. 

ProcessHandle 

A handle of an process object, representing the process for which the view should be 
mapped. The handle must grant PR0CESS_VM_0PERATI0N access. 

BaseAddress 

Points to a variable that will receive the base address of the view. If the initial value of 
this variable is not null, the view is allocated starting at the specified address, possibly 
rounded down. 

ZeroBits 

Specifies the number of high-order address bits that must be zero in the base address 
of the section view. The value of this parameter must be less than 21 and is used only 
when the operating system determines where to allocate the view, such as when 
BaseAddress is null. 

CommitSize 

Specifies the size, in bytes, of the initially committed region of the view. CommitSize is 
only meaningful for page-file backed sections; file backed sections, both data and 
image, are effectively committed at section creation time. This value is rounded up to 
the next page size boundary. 
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SectionOffset 

Optionally points to a variable that contains the offset, in bytes, from the beginning of 
the section to the view, possibly rounded down. 

ViewSize 

Points to a variable that will receive the actual size, in bytes, of the view. If the initial 
value of this variable is zero, a view of the section will be mapped starting at the speci- 
fied section offset and continuing to the end of the section. Otherwise, the initial value 
of this parameter specifies the size of the view, in bytes, and is rounded up to the next 
page size boundary. 

InheritDispostion 

Specifies how the view is to be shared by a child process created with a create process 
operation. Permitted values are drawn from the enumeration SECTION_INHERIT. 

typedef enum _SECTION_INHERIT { 

ViewShare = 1 , 

ViewUnmap = 2 
} SECTION_INHERIT ; 



AllocationType 

A set of flags that describes the type of allocation to be performed for the specified 
region of pages. The permitted values include: 



AT_EXTENDABLE_FILE 
MEM_T0P_D0WN 
SEC_N0_CHANGE 
AT_RESERVED 
AT_R0UND_T0 PAGE 



0x00002000 

0x00100000 

0x00400000 

0x20000000 

0x40000000 



// Allow view to exceed section size 
// Allocate at highest possible address 
// Disable changes to protection of pages 
// Valid but ignored 
// Adjust address and size if necessary 



Protect 

Specifies the protection for the region of initially committed pages. The protection 
must be compatible with the protection specified when the section was created. (The 
protection can be more but not less restrictive.) 

Return Value 

Returns STATUS_SUCCESS, STATUS_IMAGE_NOT_AT_BASE, 
STATUS_IMAGE_MACHINE_TYPE_MISMATCH or an error status, such as 
STATUS_INVALID_HANDLE, STATUS_ACCESS_DENIED, STATUS_CONFLICTING_ADDRESSES, 
STATUS_INVALID_VIEW_SIZE, STATUS_MAPPED_ALIGNMENT, or STATUS_PROCESS_IS_ 
TERMINATING. 

Related Win32 Functions 

MapViewOf File, MapViewOf FileEx. 

Remarks 

ZwMapViewOfSection is documented in the DDK. 

When mapping “\Device\PhysicalMemory”, the BaseAddress and SectionOffset are 
rounded down to the next page boundary. When mapping pagefile and data sections, 
BaseAddress and SectionOffset must be aligned with the system’s allocation granu- 
larity unless the AllocationType flags include AT_R0UND_T0_PAGE. In which case, they 
are rounded down to the next page boundary. 
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The AllocationType flag AT_EXTENDABLE_FILE is only present in Windows 2000 and 
is only valid for data sections backed by a file mapped with PAGE_READWRITE or 
PAGE_EXECUTE_READWRITE protection. Changes to data within the view but beyond the 
size of the backing file are not permanently stored unless the section (and implicitly 
the backing file) is extended with ZwExtendSection to encompass the changes. 



ZwUnmapViewOfSection 



ZwUnmapViewOfSection unmaps a view of a section. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwUnmapViewOfSection ( 

IN HANDLE ProcessHandle, 

IN PV0ID BaseAddress 

); 



Parameters 

ProcessHandle 

A handle of an process object, representing the process for which the view should be 
unmapped. The handle must grant PR0CESS_VM_0PERATI0N access. 

BaseAddress 

The base address of the view that is to be unmapped. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_N0T_MAPPED_VIEW, or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

UnmapViewOf File. 

Remarks 

ZwUnmapViewOfSection is documented in the DDK. 



ZwAreMappedFilesTheSame 



ZwAreMappedFilesTheSame tests whether two pointers refer to image sections backed 
by the same file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAreMappedFilesTheSame ( 

IN PV0ID Addressl , 

IN PV0ID Address2 

); 
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Parameters 

Address f 

A virtual address mapped to an image section. 

Address2 

A virtual address mapped to an image section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_ADDRESS, 
STATUS_CONFLICTING_ADDRESSES, or STATUS_NOT_SAME_DEVICE. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwAreMappedFilesTheSame is only present in Windows 2000. 

If the two pointers refer to image sections backed by the same file then 
ZwAreMappedFilesTheSame returns STATUS_SUCCESS; otherwise, it returns an error status. 
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Threads 



The system services described in this chapter create and manipulate thread objects. 






ZwCreateThread creates a thread in a process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateThread( 

OUT PHANDLE ThreadHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN HANDLE ProcessHandle , 

OUT PCLIENT_ID Clientld, 

IN PCONTEXT ThreadContext, 

IN PUSER_STACK UserStack, 

IN BOOLEAN CreateSuspended 

); 

Parameters 

ThreadHandle 

Points to a variable that will receive the thread object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the thread object. This parameter 
can be zero or any combination of the following flags: 




THREAD_TERMINATE 

THREAD_SUSPEND_RESUME 

THREAD_ALERT 

THREAD_GET_CONTEXT 

THREAD_SET_CONTEXT 

THREAD_SET_INFORMATION 

THREAD_QUERY_INFORMATION 

THREAD_SET_THREAD_TOKEN 

THREAD_IMPERSONATE 

THREAD_DIRECT_IMPERSONATION 

THREAD_ALL_ACCESS 



Terminate thread 

Suspend or resume thread 

Alert thread 

Get thread context 

Set thread context 

Set thread information 

Get thread information 

Set thread token 

Allow thread to impersonate 

Allow thread token to be impersonated 

All of the preceding + 

STANDARD RIGHTS ALL 
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Object Attributes 

Points to a structure that specifies the object’s attributes. OBJ_PERMANENT, 
OBJ_EXCLUSIVE and 0BJ_0PENIF are not valid attributes for a thread object. 

ProcessHandle 

A handle to the process in which the thread is to be created. The handle must 
grant PROCESS_CREATE_THREAD access. 

Client Id 

Points to a variable that will receive the thread and process identifiers if the call is suc- 
cessful. 

ThreadContext 

Points to a structure that specifies the initial values of the processor registers for the 
thread. 

UserStack 

Points to a structure that specifies the user mode stack of the thread. 

CreateSuspended 

A boolean specifying whether the thread should be created suspended or should be 
immediately allowed to begin execution. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

CreateThread, CreateRemoteThread. 

Remarks 

Practical examples of creating a thread using ZwCreateThread appear in Chapter 6.1, 
“Processes,” in Examples 6.1 and 6.2. 

The USER_STACK structure is defined as follows: 

typedef struct _USER_STACK { 

PVOID FixedStackBase; 

PVOID FixedStackLimit ; 

PVOID ExpandableStackBase; 

PVOID ExpandableStackLimit ; 

PVOID ExpandableStackBottom; 

} USER_STACK, *PUSER_STACK; 

Members 

FixedStackBase 

A pointer to the base of a fixed-size stack. 
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Fixed S tackLim it 

A pointer to the limit (that is, top) of a fixed-size stack. 

ExpandableStackBase 

A pointer to the base of the committed memory of an expandable stack. 

ExpandableStackLimit 

A pointer to the limit (that is, top) of the committed memory of an expandable stack. 

Expandable StackBottom 

A pointer to the bottom of the reserved memory of an expandable stack. 

Remarks 

If FixedStackBase or FixedStackLimit are not null, they are used to delimit the ini- 
tial stack of the thread; otherwise ExpandableStackBase and ExpandableStackLimit 
are used. Example 6.2 in Chapter 6 demonstrates how to initialize this structure. 



ZwOpenThread 



ZwOpenThread opens a thread object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenThread( 

OUT PHANDLE ThreadHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 
IN PCLIENT_ID Clientld 
); 



Parameters 

ThreadHandle 

Points to a variable that will receive the thread object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the thread object. This parameter 



can be zero, or any combination of the 

THREAD_TERMINATE 
THREAD_SUSPEND_RESUME 
THREAD_ALERT 
THREAD_GET_CONTEXT 
THREAD_SET_CONTEXT 
THREAD_SET_INFORMATION 
THREAD_QUERY_INFORMATION 
THREAD_SET_THREAD_TOKEN 
THREAD_IMPERSONATE 
THREAD_DIRECT_IMPERSONATION 
THREAD_ALL_ACCESS 



following flags: 

Terminate thread 

Suspend or resume thread 

Alert thread 

Get thread context 

Set thread context 

Set thread information 

Get thread information 

Set thread token 

Allow thread to impersonate 

Allow thread token to be impersonated 

All of the preceding + 

STANDARD RIGHTS ALL 
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Object Attributes 

Points to a structure that specifies the object’s attributes. OBJ_PERMANENT, 
OBJ_EXCLUSIVE and 0BJ_0PENIF are not valid attributes for a thread object. 

Clientld 

Optionally points to a structure that contains optionally the process identifier 
(UniqueProcess) and the identifier of a thread in the process (UniqueThread). 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_NOT_FOUND, STATUS_INVALID_PARAMETER_MIX, or 
STATUS_I NVALI D_PARAMETER . 

Related Win32 Functions 

OpenThread. 

Remarks 

Thread objects can be given names in the same way as other objects. 

The thread to be opened is identified either by Obj ectAttnibutes, ObjectName, or 
Clientld; it is an error to specify both. 

If Clientld . UniqueProcess is not zero, it must be the identifier of the process in 
which the thread resides. 

If the caller has SeDebugPrivilege, the check of whether the caller is granted access 
to the thread by its ACL is bypassed, (This behavior can be disabled under Windows 
NT 4.0 by setting the NtGlobalFlag FLG_IGNORE_DEBUG_PRIV.) 



ZwTcrminatcThrcad 



ZwTerminateThread terminates a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwTerminateThread ( 

IN HANDLE ThreadHandle OPTIONAL, 

IN NTSTATUS ExitStatuS 

); 

Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_TERMINATE access. If this 
value is zero, the current thread is terminated. 

ExitStatus 

Specifies the exit status for the thread. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_CAN T_TERMINATE_SELF. 

Related Win32 Functions 

Ter'minateThr'ead, ExitThread. 

Remarks 

Ter'minateThr'ead exposes the full functionality of ZwTerminateThread. 

The current thread can be terminated by calling ZwTerminateThread with a thread 
handle of either zero or NtCurrentThread ( ) . If the thread is the last thread in the 
process and ThreadHandle is zero, the error status STATUS_CANT_TERMINATE_SELF is 
returned. 

ZwTerminateThread does not deallocate the initial stack of the thread because 
ZwCreateThread did not allocate it. The initial stack can be explicitly de-allocated (by 
calling ZwFreeVirtualMemory) after the thread has been terminated (when the thread 
object becomes signalled). 



ZwQuerylnformationThread 



ZwQuerylnformationThread retrieves information about a thread object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationThread ( 

IN HANDLE ThreadHandle, 

IN THREADINFOCLASS Threadlnf ormationClass , 

OUT PVOID Threadlnf ormation, 

IN ULONG ThreadlnformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_QUERY_INFORMATION 

access. 

ThreadlnformationClass 

Specifies the type of thread information to be queried. The permitted values are drawn 
from the enumeration THREADINFOCLASS, described in the section 
“THREADINFOCLASS”. 

Thread Information 

Points to a caller-allocated buffer or variable that receives the requested thread 
information. 
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ThreadlnformationLength 

Specifies the size in bytes of Threadlnf ormation, which the caller should set according 
to the given Threadlnf ormationClass. 

Return Length 

Optionally points to a variable, which receives the number of bytes actually returned 
to Threadlnf ormation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or 
STATUS_I N F0_L ENGTH_M I S MATCH . 

Related Win32 Functions 

GetThreadPriority, GetThreadPriorityBoost, GetThreadTimes, GetExitCodeThread, 
GetThreadSelectorEntry. 

Remarks 

None. 



ZwSetlnformationThread 



ZwSetlnformationThread sets information affecting a thread object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationThread ( 

IN HANDLE ThreadHandle, 

IN THREADINFOCLASS Threadlnf ormationClass , 

IN PVOID Threadlnformation, 

IN ULONG ThreadlnformationLength 

); 



Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_QUERY_INFORMATION 
access. Some information classes also require THREAD_SET_THREAD_TOKEN access. 

Th readlnf ormationClass 

Specifies the type of thread information to be set. The permitted values are drawn 
from the enumeration THREADINFOCLASS, described in the following section. 

Threadlnformation 

Points to a caller-allocated buffer or variable that contains the thread information to 
be set. 
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ThreadlnformationLength 

Specifies the size in bytes of Threadlnf ormation, which the caller should set according 
to the given Threadlnf ormationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, 
STATUS_INFO_LENGTH_MISMATCH, or STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

SetThreadAf f inityMask, SetThreadldealProcessor, SetThreadPriority, and 
SetThreadPriorityBoost. 

Remarks 

None. 



THREADINFOCLASS 



Query Set 

typedef enum _THREADINFOCLASS { 



ThreadBasicInformation, 


a 


0 


Y 


N 


ThreadTimes, 


a 


1 


Y 


N 


ThreadPriority , 


a 


2 


N 


Y 


ThreadBasePriority , 


a 


3 


N 


Y 


ThreadAff inityMask , 


a 


4 


N 


Y 


ThreadlmpersonationToken, 


a 


5 


N 


Y 


ThreadDescriptorTableEntry , 


a 


6 


Y 


N 


ThreadEnableAlignmentFaultFixup, 


a 


7 


N 


Y 


ThreadEventPair, 


a 


8 


N 


Y 


ThreadQuerySetWin32StartAddress, 


a 


9 


Y 


Y 


ThreadZeroTlsCell , 


a 


10 


N 


Y 


ThreadPerformanceCount , 


a 


11 


Y 


N 


ThreadAmILastThread , 


a 


12 


Y 


N 


ThreadldealProcessor, 


a 


13 


N 


Y 


ThreadPriorityBoost , 


a 


14 


Y 


Y 


ThreadSetTlsArrayAddress , 


a 


15 


N 


Y 


ThreadlsIoPending, 


a 


16 


Y 


N 


ThreadHideFromDebugger 


a 


17 


N 


Y 



} THREADINFOCLASS; 



ThreadBasicInformation 



typedef struct _THREAD_BASIC_INFORMATION { // Information Class 0 
NTSTATUS ExitStatus; 

PNT_TIB TebBaseAddress; 

CLIENT_ID Clientld; 

KAFFINITY Aff inityMask ; 

KPRIORITY Priority; 

KPRIORITY BasePriority ; 

} THREAD_BASIC_INFORMATION , *PTHREAD_BAS I C_IN FORMATION ; 
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Members 

ExitStatus 

The exit status of the thread. If the process has not exited, this member normally 
contains STATUS_SUCCESS. 

TebBaseAddress 

The base address of the Thread Environment Block. 

Clientldentifier 

The thread identifier and the identifier of the process in which the thread resides. 

AffinityMask 

The processor affinity mask of the thread. 

Priority 

The current priority of the thread. 

BasePriority 

The base priority of the thread. 

Remarks 

None. 

ThreadTimes 

typedef struct _KERNEL_USER_TIMES { // Information Class 1 
LARGE_INTEGER CreateTime; 

LARGE_INTEGER ExitTime; 

LARGE_INTEGER KernelTime; 

LARGE_INTEGER UserTime; 

} KERNEL_USER_TIMES , *PKERNEL_USER_TIMES; 

Members 

CreateTime 

The creation time of the thread in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

ExitTime 

The exit time of the thread in the standard time format (that is, the number of 100- 
nanosecond intervals since January 1, 1601). For threads which have not exited, this 
value is zero. 

KernelTime 

The time spent executing in kernel mode by the thread, measured in units of 100- 
nanoseconds. 
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UserTime 

The time spent executing in user mode by the thread, measured in units of 100- 
nanoseconds. 

Remarks 

None. 



ThreadPriority 



KPRIORITY Priority; // Information Class 2 

This information class can only be set. It sets the priority of the thread. Priority should 
be a valid priority value (that is, a value in the range 1 to 31). 



Thre adB asePriority 



LONG BasePriority ; // Information Class 3 

This information class can only be set. It sets the base priority of the thread. 
BasePriority is interpreted as a delta with respect to the current base priority; it can 
be positive or negative. 



ThreadAffmityMask 



KAFFINITY Aff inityMask; // Information Class 4 

This information class can only be set. It sets the processor affinity mask for the thread. 



ThreadlmpersonationToken 



HANDLE ImpersonationToken; // Information Class 5 

This information class can only be set. It sets the impersonation token of the thread. 
ImpersonationToken should either be a handle to an impersonation token granting 
TOKEN_IMPERSONATE access, or zero to terminate the impersonation. 



ThrcadEnablcAlignmcntFaultFixup 



BOOLEAN EnableAlignmentFaultFixup; // Information Class 7 

This information class can only be set. It sets a flag in the thread indicating whether 
alignment faults should be fixed up. An alignment fault occurs, for example, when a 
word is loaded from an odd byte address and is fixed up by reading the word as two 
separate bytes. Alignment faults are only enabled on Intel processors when the AM 
flag is set in the CrO register, the AC flag is set in the E Flags register, and the current 
privilege level is 3 (user mode). 
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ThreadEventPair 



HANDLE EventPair; // Information Class 8 

This information class can only be set. It sets the EventPair of the thread. EventPair 
should be a handle to an EventPair granting STANDARD_RIGHTS_ALL access. If the 
thread already has an EventPair, the existing EventPair is first dereferenced. 

The thread EventPair is used by the routines ZwSetLowWaitHighThread and 
ZwSetHighWaitLowThread. 

In Windows 2000, this information class has been removed and 
STATUS INVALID INFO CLASS is returned. 



ThreadQuerySetWin3 2StartAddress 



PVOID Win32StartAddress; // Information Class 9 
This information class can be both queried and set. 

For the Intel platform, the initial value of this variable is the value of the Eax register 
in the Context structure passed to ZwCreateThread. If the thread is started using the 
thread start thunk in kernel32.dll, Eax contains the “Win32 start address.” 

The field in the ETHREAD structure that is queried and set by this information class is 
also used to hold the “LpcReceivedMessageld.” Any thread that has called 

ZwReplyWaitReplyPort or ZwReplyWaitReceivePort will have modified this field. 

In David Solomons Inside Windows NT (second edition, Microsoft Press, 1998) the 
output of the resource kit utility “tlist” is included to illustrate the difference 
between the actual start address and the Win32 start address; one of the Win32 start 
addresses in the tlist output is less than 0x10000 (normally a reserved region of the 
address space) — this thread is called ZwReplyWaitReceivePort. 



ThrcadZcroTlsCcll 



UL0NG ZeroTlsCell; // Information Class 10 

This information class can only be set. It zeroes the Thread Local Storage cell identi- 
fied by ZeroTlsCell (ZeroTlsCell is a TLS index). 



ThrcadPcrformanccCount 



LARGE_INTEGER Perf ormanceCount ; // Information Class 11 

The performance count is always zero. 



ThreadAmILastThread 



UL0NG AmILastThread; // Information Class 12 

AmILastThread is interpreted as a boolean and indicates whether the thread is the only 
one in the process. 
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ThreadldealProcessor 



ULONG IdealProcessor; // Information Class 13 

This information class can only be set. It specifies the number of the preferred proces- 
sor for the thread. A value of MAXIMUM_PROCESSORS tells the system that the thread has 
no preferred processor. 



ThrcadPriorityBoost 



ULONG PriorityBoost ; // Information Class 14 

This information class can be both queried and set. PriorityBoost is interpreted as a 
boolean and specifies whether priority boosting is enabled or disabled. 



ThrcadSctTlsArrayAddrcss 



PVOID SetTlsArrayAddress; // Information Class 15 

This information class can only be set. It sets the address of the Thread Local Storage 
array. 



ThrcadlsIoPcnding 



ULONG IsIoPending; // Information Class 16 

IsIoPending is interpreted as a boolean and indicates whether the thread has any out- 
standing IRPs (I/O Request Packets). 



ThreadHideFromDebugger 



This information class can only be set. It disables the generation of debug events for 
the thread. This information class requires no data, and so Thread Information may be 
a null pointer .Threadlnf ormationLength should be zero. 



ZwSuspendThread 



ZwSuspendThread suspends the execution of a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSuspendThread ( 

IN HANDLE ThreadHandle , 

OUT PULONG PreviousSuspendCount OPTIONAL 

); 
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Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_SUSPEND_RESUME access. 

Previous Suspend Count 

Optionally points to a variable that receives the previous suspend count of the thread. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_SUSPEND_COUNT_EXCEEDED, or 
STATUS_THREAD_IS_TERMINATING. 

Related Win32 Functions 

SuspendThread. 

Remarks 

SuspendThread exposes the full functionality of ZwSuspendThread. 



ZwResumeThread 



ZwResumeThread decrements the suspend count of a thread and resumes the execution 
of the thread if the suspend count reaches zero. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwResumeThread ( 

IN HANDLE ThreadHandle, 

OUT PULONG PreviousSuspendCount OPTIONAL 

); 



Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_SUSPEND_RESUME access. 

PreviousSuspendCount 

Optionally points to a variable that receives the previous suspend count of the thread. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS INVALID HANDLE. 
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Related Win32 Functions 

ResumeThread. 



Remarks 

ResumeThread exposes the full functionality of ZwResumeThread. 



ZwGetContextThread 



ZwGetContextThread retrieves the execution context of a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwGetContextThread ( 

IN HANDLE ThreadHandle , 

OUT PCONTEXT Context 

); 



Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_GET_CONTEXT access. 

Context 

Points to a caller-allocated buffer or variable that receives the thread context 
information. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

GetThreadContext. 

Remarks 

GetThreadContext exposes the full functionality of ZwGetContextThread. 

The ContextFlags member of the CONTEXT structure specifies which aspects of the 
thread’s context should be retrieved. 

For the Intel family of processors, the debug registers are only valid if at least one of 
DrO-3 is enabled in Dr7 — regardless of whether CONTEXT_DEBUG_REGISTERS is set. This 
means that Dr6 cannot reliably be used to detect the difference between a single step 
and a debug register breakpoint. 
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ZwSetContextThread 



ZwSetContext sets the execution context of a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetContextThread ( 

IN HANDLE ThreadHandle, 

IN PCONTEXT context 

); 



ThreadHandle 

A handle to a thread object. The handle must grant THREAD_SET_CONTEXT access. 

Context 

Points to a caller-allocated buffer or variable that contains the thread context 
information. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

SetThreadContext. 

Remarks 

SetThreadContext exposes the full functionality of ZwSetContextThread. 

The ContextFlags member of the CONTEXT structure specifies which aspects of the 
threads context should be set. 

Some values in the CONTEXT structure that cannot be specified are silently set to the 
correct value. This includes bits in the CPU status register that specify the privileged 
processor mode, global enabling bits in the debugging register, and other states that 
must be controlled by the operating system. 

For the Intel family of processors, the sanitization of the EFlags register disables the 
seemingly harmless Restart Flag (RF).This is a nuisance when developing a user 
mode debugger that implements some breakpoints with the debug registers; because to 
continue from a breakpoint the breakpoint, must first be removed, then the thread 
must be single stepped, and finally the breakpoint must be restored. To ensure that no 
other thread passes through the breakpoint while it is temporarily removed, all other 
threads should be suspended until the breakpoint is restored. 



ZwQueueApcThread 



ZwQueueApcThread queues a user APC request to the APC queue of a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 
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ZwQueueApcThread ( 

IN HANDLE ThreadHandle , 

IN PKNORMAL_ROUTINE ApcRoutine, 
IN PVOID ApcContext OPTIONAL, 

IN PVOID Argumentl OPTIONAL, 

IN PVOID Argument2 OPTIONAL 

); 



Parameters 



ThreadHandle 

A handle to a thread object. The handle must grant THREAD_SET_CONTEXT access. 

ApcRoutine 

A pointer to the routine to execute. The signature of the routine is: 

VOID (NTAPI *PKN0RMAL_R0UTINE) (PVOID ApcContext, 

PVOID Argumentl, PVOID Argument2); 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

Argumentl 

A void pointer that can be used to provide the ApcRoutine with additional 
information. 

Argument2 

A void pointer that can be used to provide the ApcRoutine with additional 
information. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

QueueUserApc. 

Remarks 

The APCs created by ZwQueueApcThread are termed “User APCs” and are only called 
at well-defined points in the execution of thread to which they are queued. 
Specifically, the thread must either call a wait service specifying that alerts are enabled, 
or it must call ZwTest Alert. 

If a wait service detects that there are queued user APCs for the thread, it returns with 
status STATUS USER APC. 
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ZwTestAlert 



ZwTestAlert tests whether a thread has been alerted. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwTestAlert( 

VOID 

); 



Parameters 

None. 



Return Value 

Returns STATUS_SUCCESS or STATUS_ALERTED. 

Related Win32 Functions 

None. 



Remarks 

ZwTestAlert tests whether the current thread has been alerted (and clears the alerted 
flag). It also enables the delivery of queued user APCs. 



ZwAlertThread 



ZwAlertThread wakes a thread from an alertable wait. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAlertThread ( 

IN HANDLE ThreadHandle 

); 



Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_ALERT access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 



None. 
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Remarks 

An alert is similar to a user APC without the procedure call. It has the same effect on 
wait services and is only distinguishable by the return status (STATUS_ALERTED rather 
than STATUS_USER_APC). 

The Win32 wrappers around the alertable system services check for a return status of 
STATUS_ALERTED and restart the alertable wait if this value is returned. Thus, 
ZwAlertThread cannot be used to wake a thread that is sleeping as a result of a call to 
SleepEx, for example. 



ZwAlertResumeThread 



ZwAlertResumeThread wakes a thread from a possibly suspended alertable wait. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAlertResumeThread ( 

IN HANDLE ThreadHandle , 

OUT PULONG PreviousSuspendCount OPTIONAL 

); 



Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_SUSPEND_RESUME access. 

PreviousSuspendCount 

Optionally points to a variable that will receive the previous suspend count of the 
thread. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

If the thread was in an alertable wait state when it was suspended, 
ZwAlertResumeThread resumes the thread and alerts it so that it returns immediately 
from the wait with status STATUS ALERTED. 
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ZwRegisterThreadTerminatePort 



ZwRegisterThreadTerminatePort registers an LPC port that should be sent a message 
when the thread terminates. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRegisterThreadTerminatePort ( 

IN HANDLE PortHandle 

); 

Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

ZwRegisterThreadTerminatePort adds the port to the list of ports that will receive an 
LPC message when the current thread terminates. 

The message has a MessageType of LPC_CLIENT_DIED and contains 8 bytes of data, 
specifically the creation time of the thread in the standard time format (that is, the 
number of 100-nanosecond intervals since January 1, 1601). 



ZwImpersonateThread 



ZwImpersonateThread enables one thread to impersonate the security context of 
another. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwImpersonateThread ( 

IN HANDLE ThreadHandle, 

IN HANDLE TargetThreadHandle , 

IN PSECURITY_QUALITY_OF_SERVICE SecurityQos 

); 

Parameters 

ThreadHandle 

A handle to the thread which is to impersonate another thread. The handle must grant 
THREAD_IMPERS0NATI0N access. 

TargetThreadHandle 

A handle to the thread which is to be impersonated. The handle must grant 

THREAD DIRECT IMPERSONATE access. 
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Security Qos 

Points to a structure that specifies the security Quality of Service. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The impersonation is ended by calling ZwSetlnformationThread with an informa- 
tion class of Thr'eadlmpersonationToken, specifying an ImpersonationToken handle of 
zero. 



ZwImpersonateAnonymousToken 



ZwImpersonateAnonymousToken sets the impersonation token of a thread to the 
anonymous token (a token with no privileges and “Everyone” as the sole group 
membership) . 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwImpersonateAnonymousToken ( 

IN HANDLE ThreadHandle 

); 

Parameters 

ThreadHandle 

A handle to a thread object. The handle must grant THREAD_IMPERSONATION access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwImpersonateAnonymousToken is only present in Windows 2000. 

The impersonation is ended by calling ZwSetlnformationThread with an information 
class of ThreadlmpersonationToken, specifying an ImpersonationToken handle of 



zero. 
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Processes 



The system services described in this chapter create and manipulate process objects. 






ZwCreateProcess creates a process object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateProcess( 

OUT PHANDLE ProcessHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN HANDLE InheritFromProcessHandle , 

IN BOOLEAN InheritHandles , 

IN HANDLE SectionHandle OPTIONAL, 

IN HANDLE DebugPort OPTIONAL, 

IN HANDLE ExceptionPort OPTIONAL 
); 

Parameters 

ProcessHandle 

Points to a variable that will receive the process object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the process object. This parame- 
ter can be zero, or any combination of the following flags: 




PROCESS_TERMINATE 

PROCESS_CREATE_THREAD 

PROCESS_SET_SESSIONID 

PR0CESS_VM_0PERATI0N 

PROCESS_VM_READ 

PROCESS_VM_WRITE 

PROCESS_DUP_HANDLE 

PROCESS_CREATE PROCESS 



Terminate process 

Create threads in process 

Set process session id 

Protect and lock memory of process 

Read memory of process 

Write memory of process 

Duplicate handles of process 

Bequeath address space and handles to 

new process 
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PR0CESS_SET_QU0TA 

PR0CESS_SET_INF0RMATI0N 

PROCESS_QUERY_INFORMATION 

PROCESS_SET_PORT 

PROCESS_ALL_ACCESS 



Set process quotas 
Set information about process 
Query information about process 
Set process exception or debug port 
All of the preceding + 
STANDARD_RIGHTS_ALL 



Object Attributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, 
and OBJ_OPENIF are not valid attributes for a process object. 

Inheri tFromProcessHandle 

A handle to the process object from which virtual address space and handles can be 
inherited. The handle must grant PROCESS_CREATE_PROCESS access. 

InheritHandles 

Specifies whether open inheritable handles should be inherited from the process 
referred to by InheritFromProcessHandle. 

SectionHandle 

Optionally specifies a handle to an image section that grants SECTION_MAP_EXECUTE 
access. If this value is zero, the new process inherits the address space from the process 
referred to by InheritFromProcessHandle. In Windows 2000 the lowest bit specifies 
(when set) that the process should not be associated with the job of the 
InheritFromProcessHandle process. 

DebugPort 

Optionally specifies a handle to a port that will receive debug messages. If this value is 
zero, no debug messages are sent. The handle need not grant any particular access. The 
circumstances under which messages are sent to the debug port and their content are 
described in Chapter 20, “Exceptions and Debugging.” 

ExceptionPort 

Optionally specifies a handle to a port that will receive exception messages. If this 
value is zero, no exception messages are sent. The handle need not grant any particular 
access. The circumstances under which messages are sent are sent to the exception port 
and their content is described in Chapter 20. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

CreateProcess, CreateProcessAsUser. 
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Remarks 

The process created does not contain any threads. 

The include file ntdef.h contains the following comments and definition: 

// Low order two bits of a handle are ignored by the system and available 
// for use by application code as tag bits. The remaining bits are opaque 
// and [ . . . ] 

#define OBJ_HANDLE_TAGBITS 0X00000003L 

This property of handles allows the lowest order bit of SectionHandle to be used to 
specify whether the created process should belong to the job of the process from 
which it inherits. If the job limits do not allow a new process to break away from the 
job, ZwCreateProcess fails with STATUS_ACCESS_DENIED. 

Because Win32 programs do not normally inherit an address space and only occasion- 
ally make use of the ability to inherit handles, another way of creating a process which 
does not belong to the job (if any) of its creator is to specify some other process (that 
is not part of the job) as the “inherit from process.” 

Practical examples of creating a process and thread from an image section and by 
inheriting address space (forking) appear in Examples 6.1 and 6.2, after the necessary 
ancillary routines have been introduced. 

The InheritedFromUniqueProcessId member of the PROCESS_BASIC_INFORMATION struc- 
ture is often interpreted as being the identifier of the parent process, and in a sense this 
is correct. However, it is not necessarily the identifier of the process that is called 
ZwCreateProcess, but rather the identifier of the process whose handle is passed as the 
InheritFromProcessHandle parameter; most of the time, these are one and the same 
process. 



ZwOpenProcess 



ZwOpenProcess opens a process object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenProcess( 

OUT PHANDLE ProcessHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 
IN PCLIENT_ID Clientld OPTIONAL 
); 



Parameters 

ProcessHandle 

Points to a variable that will receive the process object handle if the call is successful. 
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DesiredAccess 

Specifies the type of access that the caller requires to the process object. This parameter 
can be zero, or any combination of the following flags: 



PROCESS_TERMINATE 

PROCESS_CREATE_THREAD 

PROCESS_SET_SESSIONID 

PR0CESS_VM_0PERATI0N 

PROCESS_VM_READ 

PROCESS_VM_WR I TE 

PROCESS_DUP_HANDLE 

PROCESS_CREATE_PROCESS 

PR0CESS_SET_QU0TA 

PR0CESS_SET_INF0RMATI0N 

PROCESS_QUERY_INFORMATION 

PROCESS_SET_PORT 

PROCESS_ALL_ACCESS 



Terminate process 

Create threads in process 

Set process session id 

Protect and lock memory of process 

Read memory of process 

Write memory of process 

Duplicate handles of process 

Bequeath address space and handles to 

new process 

Set process quotas 

Set information about process 

Query information about process 

Set process exception or debug port 

All of the preceding + 

STANDARD_RIGHTS_ALL 



Object Attributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, 
and OBJ_OPENIF are not valid attributes for a process object. 

Client Id 

Optionally points to a structure that contains the process id (UniqueProcess) and 
optionally the id of a thread in the process (UniqueThread) . 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_NOT_FOUND, STATUS_INVALID_PARAMETER_MIX, or 
STATUS_INVAL ID PARAMETER. 

Related Win32 Functions 

OpenProcess. 

Remarks 

Process objects can be given names in the same way as other objects. This name is dif- 
ferent from what is commonly referred to as the process name, which is actually the 
name of the executable file from which the initial section object of the process was 
created. 

The process to be opened is identified either by ObjectAttributes.ObjectName or 
Clientld; it is an error to specify both. 

If Clientld .UniqueThread is not zero, it must be the identifier of a thread in the process 
identified by Client Id. UniqueProcess. 

If the caller has SeDebugPrivilege, the check of whether the caller is granted access to 
the process by its ACL is bypassed. (This behavior can be disabled under Windows NT 
4.0 by setting the NtGlobalFlag FLG_IGNORE_DEBUG_PRIV.) 
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ZwTerminateProcess 



ZwTerminateProcess terminates a process and the threads that it contains. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwTerminateProcess ( 

IN HANDLE ProcessHandle OPTIONAL, 

IN NTSTATUS ExitStatus 

); 

Parameters 

ProcessHandle 

A handle to a process object. The handle must grant PROCESS_TERMINATE access. If this 
value is zero, the current process is terminated. 

ExitStatus 

Specifies the exit status for the process and for all threads terminated as a result of this 
call. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_PROCESS_I S_TERM I NAT I NG. 

Related Win32 Functions 

TerminateProcess, ExitProcess. 

Remarks 

TerminateProcess exposes the full functionality of ZwTerminateProcess. 



ZwQuerylnformationProcess 



ZwQuerylnformationProcess retrieves information about a process object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationProcess ( 

IN HANDLE ProcessHandle, 

IN PROCESSINFOCLASS Processlnf ormationClass , 

OUT PVOID Processlnformation, 

IN ULONG ProcessInformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 



Parameters 

ProcessHandle 

A handle to a process object. The handle must grant PROCESS_QUERY_IN FORMATION 
access. Some information classes also require PROCESS_VM_ READ access. 
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Process Information Class 

Specifies the type of process information to be queried. The permitted values are 
drawn from the enumeration PROCESSINFOCLASS, described in the following section. 

Process Information 

Points to a caller-allocated buffer or variable that receives the requested process infor- 
mation. 

Process Inf ormationLength 

Specifies the size in bytes of Processlnformation, which the caller should set according 
to the given ProcessInformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Processlnf ormation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, STATUS_INFO_LENGTH_MISMATCH, or 
STATUS_NOT_SUP PORTED. 

Related Win32 Functions 

GetProcessAff inityMask, GetProcessPriorityBoost, GetProcessWorkingSetSize, 
GetProcessTimes, GetExitCodeProcess, SetErrorMode. 

Remarks 

None. 



ZwSetlnformationProcess 



ZwSetlnformationProcess sets information affecting a process object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationProcess ( 

IN HANDLE ProcessHandle, 

IN PROCESSINFOCLASS Processlnf ormationClass , 

IN PVOID Processlnformation, 

IN ULONG ProcessInformationLength 

); 



Parameters 

ProcessHandle 

A handle to a process object. The handle should normally grant 
PROCESS_SET_INFORMATION access. Some information classes require in addition 
or instead PROCESS_VM_WRITE, PROCESS_SET_PORT, PROCESS_SET_QUOTA or 
PROCESS SET SESSIONID access. 
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Process Information Class 

Specifies the type of process information to be set. The permitted values are drawn 
from the enumeration PROCESSINFOCLASS, described in the following section. 

Process Information 

Points to a caller-allocated buffer or variable that contains the process information to 
be set. 

Process Inf ormationLength 

Specifies the size in bytes of Processlnformation, which the caller should set according 
to the given ProcessInformationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, STATUS_INFO_LENGTH_MISMATCH, 
STATUS_PORT_ALREADY_SET, STATUS_PRIVILEGE_NOT_HELD, or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

SetProcessAff inityMask, SetProcessPriorityBoost, SetProcessWorkingSetSize, 
SetErrorMode. 

Remarks 

None. 



PROCESSINFOCLASS 



Query Set 

typedef enum _PROCESSINFOCLASS { 



ProcessBasicInformation, 


// 


0 


Y 


N 


ProcessQuotaLiinits , 


a 


1 


Y 


Y 


ProcessIoCounters, 


a 


2 


Y 


N 


ProcessVmCounters, 


a 


3 


Y 


N 


ProcessTimes, 


a 


4 


Y 


N 


ProcessBasePriority, 


a 


5 


N 


Y 


ProcessRaisePriority , 


a 


6 


N 


Y 


ProcessDebugPort , 


a 


7 


Y 


Y 


ProcessExceptionPort , 


a 


8 


N 


Y 


ProcessAccessToken , 


a 


9 


N 


Y 


ProcessLdt Informat ion, 


a 


10 


Y 


Y 


ProcessLdtSize, 


a 


11 


N 


Y 


ProcessDef aultHardErrorMode, 


a 


12 


Y 


Y 


ProcessIoPortHandlers , 


a 


13 


N 


Y 


ProcessPooledUsageAndLimits , 


a 


14 


Y 


N 


ProcessWorkingSetWatch , 


a 


15 


Y 


Y 


ProcessUserModelOPL, 


a 


16 


N 


Y 


ProcessEnableAlignmentFault Fixup, 


a 


17 


N 


Y 


ProcessPriorityClass, 


a 


18 


N 


Y 


ProcessWx86Inf ormation , 


a 


19 


Y 


N 


ProcessHandleCount , 


a 


20 


Y 


N 


ProcessAff inityMask, 


a 


21 


N 


Y 


ProcessPriorityBoost , 


a 


22 


Y 


Y 


ProcessDeviceMap, 


a 


23 


Y 


Y 
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ProcessSession Informat ion, 
ProcessForeg round Informat ion, 
ProcessWow64Information 
} PROCESSINFOCLASS; 



// 24 Y Y 

// 25 N Y 

// 26 Y N 



ProcessBasicInformation 



typedef struct _PR0CESS_BASIC_INF0RMATI0N { // Information Class 0 
NTSTATUS ExitStatus; 

PPEB PebBaseAddress; 

KAFFINITY Af f inityMask ; 

KPRIORITY BasePriority ; 

ULONG UniqueProcessId; 

ULONG InheritedFromUniqueProcessId; 

} PR0CESS_BASIC_INF0RMATI0N , *PPR0CESS_BASIC_INF0RMATI0N ; 

Members 

ExitStatus 

The exit status of the process. If the process has not exited, this member normally 
contains STATUS__PENDING. 

PebBaseAddress 

The base address of the Process Environment Block (PEB) . 

AffinityMask 

The processor affinity mask of the process. 

BasePriority 

The base priority of the process. 

Un iqueProcessId 

The process identifier of the process. 

InheritedFromUniqueProcessId 

The process identifier of the process from which inheritable handles and address space 
may have been inherited. 



Remarks 

None. 



ProcessQuotaLimits 



typedef struct _QU0TA_LIMITS { // Information Class 1 
ULONG PagedPoolLimit ; 

ULONG NonPagedPoolLimit ; 

ULONG MinimumWorkingSetSize; 

ULONG MaximumWorkingSetSize; 

ULONG Pagef ileLimit ; 

LARGE_INTEGER TimeLimit; 

} QU0TA_LIMITS, *PQU0TA_LIMITS; 
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Members 

PagedPoolLimit 

The size in bytes of the paged pool quota of the processes sharing the quota block. 

NonPagedPoolLimit 

The size in bytes of the nonpaged pool quota of the processes sharing the quota block. 

Minimum WorkingSetSize 

The size in bytes of the minimum working set size of the process. 

Maximum WorkingSetSize 

The size in bytes of the maximum working set size of the process. 

PagefileLimit 

The size in pages of the pagefile quota of the processes sharing the quota block. 

TimeLimit 

The execution time limit of the processes sharing the quota block measured in units of 
100-nanoseconds. Execution time limits are not supported. 

Remarks 

This information class can be both queried and set. 

When setting quota limits, if MinimumWorkingSetSize and MaximumWorkingSetSize are 
both non-zero, the working set size is adjusted and the other values are ignored. 
Otherwise, the working set size is not adjusted, and if the process is still using the 
default quota block and SelncreaseQuotaPrivilege is enabled, the other quota values 
are updated. 



ProcessloCounters 



typedef struct _I0_C0UNTERS { // Information Class 2 
LARGE_INTEGER ReadOperationCount ; 

LARGE_INTEGER WriteOperationCount ; 

LARGE_INTEGER OtherOperationCount ; 

LARGE_INTEGER ReadTransf erCount ; 

LARGE_INTEGER WriteT ransf erCount ; 

LARGE_INTEGER OtherT ransf erCount ; 

} I0_C0UNTERS, *PI0_C0UNTERS; 

Members 

Read Operation Count 

The number of calls to ZwReadFile by the process. 

Wri te Opera tion Count 

The number of calls to ZwWriteFile by the process. 
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OtherOperationCount 

The number of calls to all other I/O system services such as ZwDeviceloControlFile by 
the process. 

Read TransferCount 

The number of bytes read by all calls to ZwReadFile by the process. 

WriteTransfer Count 

The number of bytes written by all calls to ZwWriteFile by the process. 

OtherTransferCount 

The number of bytes transferred to satisfy all other I/O operations such as 

ZwDeviceloControlFile by the process. 

Remarks 

Windows NT 4.0 does not support the accounting of I/O operations on a per-process 
basis, and ZwQuerySystemlnf ormation returns STATUS_NOT_SUPPORTED if this information 
class is queried. Windows 2000 supports this information class. 



ProcessVmCounters 



typedef struct _VM_C0UNTERS { // Information Class 3 
UL0NG PeakVirtualSize; 

UL0NG VirtualSize; 

UL0NG PageFaultCount ; 

UL0NG PeakWorkingSetSize; 

UL0NG WorkingSetSize; 

UL0NG QuotaPeakPagedPoolUsage; 

UL0NG QuotaPagedPoolUsage; 

UL0NG QuotaPeakNonPagedPoolUsage ; 

UL0NG QuotaNonPagedPoolUsage; 

UL0NG PagefileUsage; 

UL0NG PeakPagef ileUsage; 

} VM_C0UNTERS, *PVM_C0UNTERS; 

Members 

Peak VirtualSize 

The peak size in bytes of the virtual address space of the process. 



VirtualSize 

The size in bytes of the virtual address space of the process. 



PageFaultCount 

The number of page faults incurred by the process. 



Peak WorkingSetSize 

The peak size in bytes of the working set list of the process. 
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WorkingSetSize 

The size in bytes of the working set list of the process. 

QiwtaPeakPagedPoolUsage 

The peak size in bytes of paged pool charged to the process. 

QuotaPagedPoolUsage 

The size in bytes of paged pool charged to the process. 

QuotaPeakNonPagedPoolUsage 

The peak size in bytes of nonpaged pool charged to the process. 

QuotaNonPagedPoolUsage 

The size in bytes of nonpaged pool charged to the process. 

PagefileUsage 

The size in bytes of pagefile pages used by the process. 

PeakPagefileUsage 

The peak size in bytes of pagefile pages used by the process. 

Remarks 

None. 



ProcessTimes 



typedef struct _KERNEL_USER_TIMES { // Information Class 4 
LARGE_INTEGER CreateTime; 

LARGE_INTEGER ExitTime; 

LARGE_INTEGER KernelTime; 

LARGE_INTEGER UserTime; 

} KERNEL_USER_TIMES , *PKERNEL_USER_TIMES ; 

Members 

CreateTime 

The creation time of the process in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

ExitTime 

The exit time of the process in the standard time format (that is, the number of 100- 
nanosecond intervals since January 1, 1601). For processes which have not exited, this 
value is zero. 

KernelTime 

The sum of the time spent executing in kernel mode by the threads of the process, 
which measured in units of 100-nanoseconds. 
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UserTime 

The sum of the time spent executing in user mode by the threads of the process, 
which is measured in units of 100-nanoseconds. 

Remarks 

None. 



ProcessBasePriority 



KPRIORITY BasePriority; // Information Class 5 

This information class can only be set. It sets the base priority of the process and 
iterates over the threads of the process, setting their base priorities. 
SelncreaseBasePriorityPrivilege is needed to increase the base priority. The memory 
priority of the process is also set, based on the result of masking BasePriority with 
0x80000000. 



ProcessRaisePriority 



UL0NG RaisePriority ; // Information Class 6 

This information class can only be set. It iterates over the threads of the process, 
increasing their priority by RaisePriority (up to a maximum of the highest non- 
realtime priority). 



ProcessDebugPort 



HANDLE DebugPort; // Information Class 7 

When querying this information class, the value is interpreted as a boolean indicating 
whether a debug port has been set or not. The debug port can be set only if it was 
previously zero (in Windows NT 4.0, once set the port can also be reset to zero). The 
handle which is set must be a handle to a port object. (Zero is also allowed in 
Windows NT 4.0.) 



ProcessExceptionPort 



HANDLE ExceptionPort ; // Information Class 8 

This information class can only be set. The exception port can be set only if it was 
previously zero. The handle must be a handle to a port object. 



ProcessAccessToken 



typedef struct _PR0CESS_ACCESS_T0KEN { // Information Class 9 
HANDLE Token; 

HANDLE Thread; 

} PR0CESS_ACCESS_T0KEN , *PPR0CESS_ACCESS_T0KEN; 













1996 CH06 11.24.99 09:54 Page 145 



Processes: ProcessPooledUsageAndLimits 



145 



Members 

Token 

A handle to a primary token to assign to the process. The handle must grant 
TOKEN_ASSIGN_PRIMARY access. 

Thread 

Not used. 



Remarks 

This information class can only be set. SeAssignPrimaryTokenPr’ivilege is required 
unless the token is a Windows 2000 filtered copy of the token of the current process. 
If the token is inappropriate, ZwSetlnformationProcess may return 
STATUS_BAD_TOKEN_TYPE or STATUS _TOKEN_ALREADY_IN_USE. 



ProcessDefaultHardErrorMode 



ULONG Def aultHardErrorMode; // Information Class 12 

This information can be both queried and set. The hard error mode is a bit array of 
flags that correspond to the flags used by the Win32 function SetErrorMode, with the 
exception that the meaning of the lowest bit is inverted. The Win32 flags are: 

SEM_FAILCRITICALERRORS 0x0001 
SEM_N0GPFAULTERR0RB0X 0x0002 

SEM_NOALIGNMENTFAULTEXCEPT 0x0004 
SEM_N00PENFILEERR0RB0X 0x8000 

So, setting a hard error mode of one means do not fail critical errors. 



ProcessPooledUsageAndLimits 



typedef struct _P00LED_USAGE_AND_LIMITS { // Information Class 14 
ULONG PeakPagedPoolUsage; 

ULONG PagedPoolUsage; 

ULONG PagedPoolLimit ; 

ULONG PeakNonPagedPoolUsage; 

ULONG NonPagedPoolUsage; 

ULONG NonPagedPoolLimit ; 

ULONG PeakPagefileUsage; 

ULONG Pagef ileUsage; 

ULONG Pagef ileLimit; 

} P00LED_USAGE_AND_LIMITS, *PP00LED_USAGE_AND_LIMITS; 

Members 

PeakPagedPoolUsage 

The peak size in bytes of the paged pool charged to the processes sharing the quota 
block. 

PagedPoolUsage 

The size in bytes of the paged pool charged to the processes sharing the quota block. 
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PagedPoolLimit 

The size in bytes of the paged pool quota of the processes sharing the quota block. 

PeakNonPagedPoolUsage 

The peak size in bytes of the nonpaged pool charged to the processes sharing the 
quota block. 

NonPagedPoolUsage 

The size in bytes of the nonpaged pool charged to the processes sharing the quota 
block. 

NonPagedPoolLimit 

The size in bytes of the nonpaged pool quota of the processes sharing the quota block. 

PeakPagefileUsage 

The peak size in pages of the pagefile used by the processes sharing the quota block. 

PagefileUsage 

The size in pages of the pagefile used by the processes sharing the quota block. 

PagefileLimit 

The size in pages of the pagefile quota of the processes sharing the quota block. 

Remarks 

None. 



ProcessWorkingSetWatch 



typedef struct _PROCESS_WS_WATCH_INFORMATION { // Information Class 15 
PVOID FaultingPc; 

PVOID FaultingVa; 

} PROCESS_WS_WATCH_INFORMATION, *PPROCESS_WS_WATCH_INFORMATION ; 

Members 

FaultingPc 

Pointer to the instruction that caused the page fault. 

FaultingVa 

The virtual address referenced by the instruction. The low bit indicates whether the 
fault was soft (if set) or hard (if clear) . 

Remarks 

When setting this information class, no information is required, and so 
Processlnf ormation may be null and ProcessInformationLength should be zero. 
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When querying this information class, an array of PROCESS_WS_WATCH_INFORMATION 
structures are returned; the end of the array is marked by an element with a 
FaultingPc value of zero. 

The system records the first 1020 page faults that occur either after working set 
watching is enabled, or after the working set watch information is queried. 



Pro c e s sUs er Mo de IO PL 



UserModelOPL; // Information Class 16 

This information class can only be set and no information is required. Therefore, 
Processlnf ormation may be null and ProcessInformationLength should be zero. 

SeTcbPrivilege is required to set this information class. 

This information class is only meaningful for Intel processors; it modifies the 1/ O 
Privilege Level for the process so that the process may directly access the 1/ O ports 
and execute other instructions that are sensitive to IOPL. 



ProcessEnableAlignmentFaultFixup 



BOOLEAN EnableAlignmentFaultFixup; // Information Class 17 

This information class only can be set and is equivalent to calling 

ZwSystemlnformationProcess with an information class of 

ProcessDef aultHardErrorMode and a value of SEM_NOALIGNMENTFAULTEXCEPT. 



ProcessPriorityClass 



typedef struct _PR0CESS_PRI0RITY_CLASS { // Information Class 18 
BOOLEAN Foreground; 

UCHAR PriorityClass; 

} PR0CESS_PRI0RITY_CLASS, *PPR0CESS_PRI0RITY_CLASS; 

Members 

Foreground 

Specifies whether the process is running in the foreground. Performance factors affected 
include scheduling quantum and working set trimming and growth. 



PriorityClass 

The scheduling priority class of the process. Permitted values are zero to four (for 
Windows NT 4.0) or six (for Windows 2000). SelncreaseBasePriorityPrivilege is 
required to set PriorityClass to four. The defined values include: 



PC_IDLE 1 
PC_N0RMAL 2 
PC_HIGH 3 
PC_REALTIME 4 



PC_BEL0W_N0RMAL 5 
PC ABOVE NORMAL 6 
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Remarks 

This information class can only be set. 

Scheduling priority parameter changes are propagated to all the threads of the process. 



ProcessWx86Information 



ULONG Wx86Information; // Information Class 19 
Wx86Information always contains zero. 



ProcessHandleCount 



ULONG HandleCount ; // Information Class 20 

HandleCount receives a count of the number of open handles of the process. 



Pro c e s s Affinity Ma sk 



KAFFINITY Aff inityMask; // Information Class 21 

This information class only can be set. The specified processor affinity mask is propa- 
gated to all the threads of the process. 



ProcessPriorityBoost 



ULONG PriorityBoost ; // Information Class 22 

This information can be both queried and set. PriorityBoost is interpreted as a 
boolean and specifies whether priority boosting is enabled or disabled. Changes to 
PriorityBoost are propagated to all the threads of the process. 



ProcessDeviceMap 



typedef struct _PROCESS_DEVICEMAP_INFORMATION { // Information Class 23 
union { 

struct { 

HANDLE DirectoryHandle; 

} Set; 
struct { 

ULONG DriveMap; 

UCHAR DriveType[32] ; 

} Query; 

}; 

} PROCESS_DEVICEMAP_INFORMATION , *PPROCESS_DEVICEMAP_INFORMATION ; 

Members 

DirectoryHandle 

A handle to an object directory granting DIRECTORY_TRAVERSE access. 
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DriveMap 

A bit array representing the disk drives available to the process. 



DriveType 

An array of values representing the types of disk drives. The defined types include: 

DRIVEJJNKNOWN 0 

DRIVE_N0_R00T_DIR 1 

DRIVE_REMOVABLE 2 

DRIVE_FIXED 3 

DRIVE_REM0TE 4 

DRIVE_CDR0M 5 

DRIVE_RAMDISK 6 

Remarks 

When a symbolic fink with a name conforming to the DOS drive letter format (an 
alphabetic character followed by a colon) is created in an object directory, the device 
map of the directory is updated to reflect the presence of a new disk drive. When a 
process sets its device map to an object directory handle, it references the device map 
of the directory, giving the process access to all the disk drives symbolically linked to 
the directory with DOS format names. By default, the device map of a process refers 
to the device map associated with the object directory named “\??”. 



ProcessSessionlnformation 



typedef struct _PR0CESS_SESSI0N_INF0RMATI0N { // Information Class 24 
ULONG Sessionld; 

} PROCESS_SESSION_INFORMATION , *PPR0CESS_SESSI0N_INF0RMATI0N ; 

Members 

Sessionld 

A numeric identifier for a session. 

Remarks 

SeTcbPrivilege is required to set this information class. 

Session identifiers are used by Windows Terminal Server to distinguish between client 
sessions. 

The session identifier is stored in the EPROCESS structure, the process token, and in the 
Process Environment Block (PEB) of the target process. 



ProcessForegroundlnformation 



BOOLEAN Foreground; // Information Class 25 

Specifies whether the process is running in the foreground. The performance factors 
that are affected include scheduling quantum and working set trimming and growth. 

This information class sets one of the parameters that also can be set using the infor- 
mation class, ProcessPriorityClass. 
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ProcessWow64Information 



ULONG Wow64Information; // Information Class 26 

Wow64 Informat ion normally contains zero on the Intel platform. 

The following routines are not part of the Native API, but they perform the useful task 
of building a complex data structure in self-relative (normalized) form. The routines 
are part of the Run-Time Library (RTL) included in ntdll.dll. 



RtlCreateProcessParameters 



RtlCreateProcessParameters creates and populates the data structure used to hold the 
user mode process parameters. 

NTSTATUS 

NTAPI 

RtlCreateProcessParameters ( 

OUT PPROCESS_PARAMETERS *ProcessParameters, 

IN PUNICODE_STRING ImageFile, 

IN PUNICODE_STRING DllPath OPTIONAL, 

IN PUNICODE_STRING CurrentDirectory OPTIONAL, 

IN PUNICODE_STRING CommandLine OPTIONAL, 

IN ULONG CreationFlags, 

IN PUNICODE_STRING WindowTitle OPTIONAL, 

IN PUNICODE_STRING Desktop OPTIONAL, 

IN PUNICODE_STRING Reserved OPTIONAL, 

IN PUNICODE_STRING Reserved2 OPTIONAL 

); 



Parameters 

Process Parameters 

Points to a variable that will receive a pointer to the process parameters if the call is 
successful. 

ImageFile 

Optionally points to the image file name from which the process was created. 

DllPath 

Optionally points to the search path that was used to search for the image file and its 
referenced DLLs. 

CurrentDirectory 

Optionally points to the current directory name of the process. 

CommandLine 

Optionally points to the command line used to start the process. 

CreationFlags 

A bit array of flags. 
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WindowTitle 

Optionally points to a window title for the process. 

Desktop 

Optionally points to the name of the desktop used by the process. 

Reserved 

Related to STARTUPINFO. IpReserved. It is not used by Win32 subsystem. 

Reserved2 

Related to STARTUPINFO. cbReserved2 and STARTUPINFO. lpReserved2. It is not used by 
Win32 subsystem. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

The process parameters are created by the caller of ZwCreateProcess and copied to 
the new process. The process parameters contain pointers to strings, and to facilitate 
copying of the data to a different virtual address (in another process), these pointers 
are initially stored in normalized form (relative to the start of the structure) . They are 
converted to normal pointers after the copy is complete. 

If an optional parameter is omitted, by specifying a null pointer, the parameter value is 
copied from the process parameters of the current process, except for CommandLine, 
which is copied from I mage File. 

The process parameters are pointed to by the PEB of a process. 



RtlDestroyProcessParameters 



RtlDestroyProcessParameters deallocates the data structure used to hold the user 
mode process parameters. 

NTSTATUS 

NTAPI 

RtlDestroyProcessParameters ( 

IN PPROCESS_PARAMETERS ProcessParameters 

); 



Parameters 

ProcessParameters 

Points to the process parameters to be deallocated. 
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Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 



Remarks 

None. 



PROCESS_PARAMETERS 



typedef struct _PROCESS_PARAMETERS { 

ULONG AllocationSize; 

ULONG Size; 

ULONG Flags; 

ULONG Reserved; 

LONG Console; 

ULONG ProcessGroup; 

HANDLE hStdlnput ; 

HANDLE hStdOutput ; 

HANDLE hStdError; 

UNICODE_STRING CurrentDirectoryName ; 
HANDLE CurrentDirectoryHandle; 

UNI C0DE_STR I NG DllPath; 

UNICODE_STRING ImageFile; 

UNICODE_STRING CommandLine; 

PWSTR Environment; 

ULONG dwX; 

ULONG dwY; 

ULONG dwXSize; 

ULONG dwYSize; 

ULONG dwXCountChars; 

ULONG dwYCountChars; 

ULONG dwFillAttribute; 

ULONG dwFlags; 

ULONG wShowWindow; 

UNI C0DE_STR I NG WindowTitle; 

UNI C0DE_STR I NG Desktop; 

UNICODE_STRING Reserved; 

UNICODE_STRING Reserved2; 

} PROCESS_PARAMETERS , *PPROCESS_PARAMETERS; 



Members 

AllocationSize 

The size in bytes of virtual memory allocated to hold the process parameters. 



Size 

The size in bytes of virtual memory used to hold the process parameters. 



Flags 

A bit array of flags. 
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Reserved 

Reserved; always contains zero. 

Console 

The numeric identifier of the console to be used by the new process. A value of -1 
indicates that the process does not have access to a console, and a value of -2 indicates 
that the process should be given access to a new console. 

Process Group 

The numeric identifier of the process group of the process. 

hStdlnput 

The handle that will be used as the standard input handle for the new process if 
STARTFJJSESTDHANDLES is specified in dwFlags. 

hStd Output 

The handle that will be used as the standard output handle for the new process if 
STARTFJJSESTDHANDLES is specified in dwFlags. 

hStdError 

The handle that will be used as the standard error handle for the new process if 
STARTFJJSESTDHANDLES is specified in dwFlags. 

CurrentDirectoryName 

The name of the current directory of the process. 

CurrentDirectory Handle 

The handle to the current directory of the process. 

DllPath 

The search path that was used to search for the image file of the process and its 
referenced DLLs. 

ImageFile 

The image file name from which the process was created. 

CommandLine 

The command line used to start the process. 

Environment 

A pointer to the environment block of the process that contains the environment vari- 
able strings. 

dll’X 

The x offset, in pixels, of the upper left corner of a window if a new window is 
created, and STARTFJJSEPOSITION is specified in dwFlags. 
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dwY 

The y offset, in pixels, of the upper left corner of a window if a new window is created, 
and STARTFJJSEPOSITION is specified in dwFlags. 

dwXSize 

The width, in pixels, of a window if a new window is created, and STARTF_USESIZE is 
specified in dwFlags. 

dwYSize 

The height, in pixels, of a window if a new window is created, and STARTF_USESIZE is 
specified in dwFlags. 

dwXCountChars 

The width, in characters, of a screen buffer if a new console window is created, and 
STARTFJJSECOUNTCHARS is specified in dwFlags. 

du’YCountChars 

The height, in characters, of a screen buffer if a new console window is created, and 
STARTFJJSECOUNTCHARS is specified in dwFlags. 

dwFillAttribute 

The initial text and background colors if a new console window is created, and 
STARTFJJSEFILLATTRIBUTE is specified in dwFlags. 

dwFlags 

The bit field that determines whether certain PROCESS_PARAMETERS members are used 
when the process creates a window. 

wShowWindow 

The show state if a new window is created, and STARTFJJSESHOWWINDOW is specified in 
dwFlags. 

WindowTitle 

The window title for the process. 

Desktop 

The name of the desktop used by the process. 

Remarks 

When using the Win32 function CreateProcess to create a process, many of the 
fields of the PROCESS_PARAMETERS structure are initialized based on information in the 
STARTUPINFO structure passed as argument to CreateProcess. 

The following routines are not part of the Native API, but they gather information 
about processes which is useful to debuggers and other clients of the ToolHelp library. 

The routines are part of the RTL included in ntdll.dll. 
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RtlCreateQueryDebugBuffer 



RtlCreateQueryDebugBuffer creates the data structure required by 

RtlQueryProcessDebuglnformation. 

PDEBUG_BUFFER 

NTAPI 

RtlCreateQueryDebugBuffer ( 

IN ULONG Size, 

IN BOOLEAN EventPair 

); 

Parameters 

Size 

Optionally specifies the size of the debug buffer. If Size is zero, a default size is used. 

EventPair 

Specifies whether an EventPair should be used to synchronize the retrieval of debug 
information. If true, a thread will be created in the target process that will be used to 
service each request for information. If false, a thread is created and destroyed in the 
target process for each request. 

Return Value 

Returns a pointer to a DEBUG_BUFFER or a null pointer. 

Related Win32 Functions 

None. 

Remarks 

None. 



RtlQueryProcessDebuglnformation 



RtlQueryProcessDebuglnformation queries information about a process that is main- 
tained in user mode. 

NTSTATUS 

NTAPI 

RtlQueryProcessDebugInformation( 

IN ULONG Processld, 

IN ULONG DebuglnfoClassMask, 

IN OUT PDEBUG_BUFFER DebugBuffer 

); 



Parameters 

Processld 

Specifies the id of the process that is to be queried. 
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Debuglnfo ClassMask 

A bit array specifying which type of information is to be queried. Multiple types of 
information can be retrieved in a single call. This parameter can be any combination of 
the following flags: 



PDI 


MODULES 


0x01 


a 


The loaded modules of the process 


PDI 


BACKTRACE 


0x02 


a 


The heap stack back traces 


PDI 


HEAPS 


0x04 


a 


The heaps of the process 


PDI 


_HEAP_TAGS 


0x08 


a 


The heap tags 


PDI 


_HEAP_BLOCKS 


0x10 


a 


The heap blocks 


PDI 


LOCKS 


0x20 


a 


The locks created by the process 



DebugBuffer 

Points to an initialized DEBUG_BUFFER that will be updated to contain the requested 
information. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

There are parallels between this information about processes and the information 
returned by ZwQuerySystemlnformation about the system. For example, heaps are a 
process equivalent of system pools, and locks are a process equivalent of system 
resources. 

The reason that this information is retrieved with an RTL routine rather than a system 
service is that the information is created and maintained entirely in user mode by 
ntdll.dll — the kernel is unaware of its existence. 

The information about modules and heaps can be used to implement the ToolHelp 
functions that report on modules and heaps. Example 6.3 builds upon an earlier exam- 
ple to add this functionality. 

PSAPI does not use RtlQueryProcessDebuglnformation to retrieve process module 
information. It directly reads and interprets the virtual memory used by ntdll.dll to 
store the information. 



RtlDestroyQueryDebugBuffer 



RtlDestroyQueryDebugBuffer deallocates the data structure used by 

RtlQueryProcessDebuglnformation. 

NTSTATUS 

NTAPI 

RtlDestroyQueryDebugBuffer ( 

IN PDEBUG_BUFFER DebugBuffer 

); 
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Parameters 

DebugBujfer 

Points to the debug buffer to be deallocated. 

Return Value 

Returns STATUS_SUCCESS. 

Related Win32 Functions 

None. 

Remarks 

If there is a thread in a target process still waiting to service query requests, it is first 
terminated, and its stack deallocated. 



DEBU G_BUFFER 



typedef struct _DEBUG_BUFFER { 

HANDLE SectionHandle; 

PVOID SectionBase; 

PVOID RemoteSectionBase; 

ULONG SectionBaseDelta; 

HANDLE EventPairHandle; 

ULONG Unknown[2] ; 

HANDLE RemoteThreadHandle; 

ULONG InfoClassMask; 

ULONG SizeOflnfo; 

ULONG AllocatedSize; 

ULONG SectionSize; 

PVOID Modulelnformation; 

PVOID BackTracelnformation; 

PVOID Heaplnformation; 

PVOID Locklnformation; 

PVOID Reserved[8] ; 

} DEBUG_BUFFER, *PDEBUG_BUFFER ; 

Members 

Modulelnformation 

A pointer to the module information if this was requested. The data pointed to by 
Modulelnformation is a ULONG count of the number of modules followed immediately 
by an array of DEBUG_MODULE_INFORMATION. 

Back Tracelnformation 

A pointer to the heap stack back-trace information if this was requested. 

Heaplnformation 

A pointer to the heap information if this was requested. The data pointed to by 
Heaplnformation is a ULONG count of the number of heaps followed immediately by an 
array of DEBUG_HEAP_INFORMATION. 
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Locklnformation 

A pointer to the lock information if this was requested. The data pointed to by 
Locklnformation is a ULONG count of the number of locks followed immediately by an 
array of DEBUG_LOCK_INFORMATION. 



Remarks 

The other members of DEBUG_BUFFER are opaque. 

typedef Struct _DEBUG_MODULE_INFORMATION { // c.f. SYSTEM_MODULE_INFORMATION 
ULONG Reserved[2] ; 

ULONG Base; 

ULONG Size; 

ULONG Flags; 

USHORT Index; 

USHORT Unknown; 

USHORT LoadCount; 

USHORT ModuleNameOff set ; 

CHAR ImageName[256] ; 

} DEBUG_M0DULE_INF0RMATI0N , *PDEBUG_MODULE_INFORMATION; 

Members 

Base 

The base address of the module. 



Size 

The size of the module. 



Flags 

A bit array of flags describing the state of the module. Observed values include: 



LDRP_STATIC_LINK 0x00000002 
LDRP_IMAGE_DLL 0X00000004 
LDRP_L0AD_I N_PR0GRESS 0x00001000 
LDRP_UNLOAD_IN_PROGRESS 0x00002000 
LDRP_ENTRY_PROCESSED 0X00004000 
LDRP_ENTRY_INSERTED 0x00008000 
LDRP_CURRENT_LOAD 0x00010000 
LDRP_FAILED_BUILTIN_LOAD 0x00020000 
LDRP_DONT_CALL_FOR_THREADS 0x00040000 
LDRP_PROCESS_ATTACH_CALLED 0x00080000 
LDRP_DEBUG_SYMBOLS_LOADED 0x001 00000 
L D R P_ I MAG E_N 0T_AT_B AS E 0x00200000 
LDRP WX86 IGNORE MACHINETYPE 0x00400000 



Index 

The index of the module in the array of modules. 

Unknown 

Interpretation unknown. 

LoadCount 

The number of references to the module. 
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Mo duleName Offset 

The offset to the final filename component of the image name. 

ImageName 

The filepath of the module. 



Remarks 

None. 

typedef struct _DEBUG_HEAP_INFORMATION { 

ULONG Base; 

ULONG Flags; 

USHORT Granularity; 

USHORT Unknown; 

ULONG Allocated; 

ULONG Committed; 

ULONG TagCount; 

ULONG BlockCount ; 

ULONG Reserved[7] ; 

PVOID Tags; 

PVOID Blocks; 

} DEBUG_HEAP_INFORMATION , *PDEBUG_HEAP_INFORMATION ; 

Members 

Base 

The base address of the heap. 

Flags 

A bit array of flags describing heap options. 

Granularity 

The granularity ot allocation from the heap. 

Unknown 

Interpretation unknown. 

Allocated 

The size in bytes of memory allocated from the heap. 

Committed 

The size in bytes of the memory committed to the heap. 

TagCount 

The number of tags pointed to by Tags. 

BlockCount 

The number of blocks pointed to by Blocks. 
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Tags 

A pointer to an array of tag information. Heap tags are used to track the usage of heap 
blocks. 

Blocks 

A pointer to an array of block information. 



Remarks 

The flags PDI_HEAP_TAGS and PDI_HEAP_BLOCKS must be specified in addition to 
PDI_HEAPS if information on heap tags or blocks is required. 

typedef Struct _DEBUG_L0CK_INF0RMATI0N { // c.f. SYSTEM_L0CK_INF0RMATI0N 
PVOID Address; 

USHORT Type; 

USHORT CreatorBackTracelndex; 

ULONG OwnerThreadld; 

ULONG ActiveCount; 

ULONG ContentionCount ; 

ULONG EntryCount; 

ULONG RecursionCount ; 

ULONG NumberOfSharedWaiters; 

ULONG NumberOf ExclusiveWaiters; 

} DEBUG_L0CK_INF0RMATI0N , *PDEBUG_L0CK_INF0RMATI0N ; 

Members 

Address 

The address of the lock structure. 

Type 

The type of the lock. This is either RTL_CRITSECT_TYPE (0) or RTL_RESOURCE_TYPE (1) . 

CreatorBack Tracelndex 

Normally contains zero. 

OwnerThreadld 

The thread identifier of the owner of the lock (the exclusive owner if the lock is a 
resource) . 

ActiveCount 

The number of threads granted access to the lock. Critical sections count from -1, and 
resources count from 0. 

ContentionCount 

The number of times a thread had to wait for the lock. 

EntryCount 

The number of times a critical section has been entered. This does not include the 
number of times that the critical section was entered without waiting. 



RecursionCount 
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The number of times a thread has recursively entered a critical section. 

NumberOfShared Waiters 

The number of threads waiting for shared access to the resource. 

NumberOfExclusive Waiters 

The number of threads waiting for exclusive access to the resource. 



Remarks 

There are two types of user mode locks: critical sections and resources. The resource 
lock is similar in functionality to the kernel mode resource lock and provides multiple 
reader, single writer functionality. 



Example 6.1: Forking a Win32 Process 



#include "ntdll.h" 

#include <stdio.h> 

namespace NT { 
extern "C" { 

NTSTATUS 

NTAPI 

CsrClientCallServer( 

IN PVOID Message, 

IN PVOID, 

IN ULONG Opcode, 

IN ULONG Size 

); 

} 

} 

VOID InheritAll() 

{ 

ULONG n = 0x1000; 

PULONG p = new UL0NG[n] ; 

while (NT : :ZwQuerySystemInformation(NT : :SystemHandleInformation, 

p, n * sizeof *p, 0) 

== STATUS_INFO_LENGTH_MISMATCH) 
delete [] p, p = new UL0NG[n *= 2]; 

NT: :PSYSTEM_HANDLE_INFORMATION h = NT: : PSYSTEM_HANDLE_INFORMATION(p + 1); 

ULONG pid = GetCurrentProcessId( ) ; 

for (ULONG i = 0; i < *p; i++) 
if ( h [ i ] . Processld == pid) 

SetHandleInformation(HANDLE(h[i] .Handle) , 

HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) ; 

delete [] p; 



VOID InformCsrss (HANDLE hProcess, HANDLE hThread, ULONG pid, ULONG tid) 

{ 



struct CSRSS_MESSAGE { 
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ULONG Unknownl ; 
ULONG Opcode; 
ULONG Status; 
ULONG Unknown2; 



struct { 

NT : : PORT_MESSAGE PortMessage; 

CSRSS_MESSAGE CsrssMessage ; 

PR0CESS_INF0RMATI0N Processlnf ormation ; 

NT: :CLIENT_ID Debugger; 

ULONG CreationFlags; 

ULONG VdmInfo[2] ; 

} csrmsg = {{0}, {0}, {hProcess, hThread, pid, tid}, {0}, 0, {0}}; 
NT: :CsrClientCallServer(&csrmsg, 0, 0x10000, 0x24); 

} 

declspec(naked) int child() 

{ 

typedef BOOL (WINAPI *CsrpConnectToServer) (PWSTR) ; 

CsrpConnectToServer(0x77F8F65D) (L" WWindows" ) ; 

asm mov eax, 0 

asm mov esp, ebp 

asm pop ebp 

asm ret 

} 



#pragma optimize( "y " , off) // disable frame pointer omission 

int fork() 

{ 

HANDLE hProcess, hThread; 

InheritAll( ) ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa}; 

NT: :ZwCreateProcess(&hProcess, PROCESS_ALL_ACCESS, &oa, 

NtCurrentProcess( ) , TRUE, 0, 0, 0); 

NT:: CONTEXT context = {CONTEXT_FULL 

j CONTEXT_DEBUG_REGISTERS 
j CONTEXT_FLOATING_POINT} ; 

NT : :ZwGetContextThread(NtCurrentThread( ) , &context) ; 
context. Eip = ULONG(child) ; 

MEMORY_BASIC_INFORMATION mbi; 

NT : :ZwQueryVirtualMemory (NtCurrentProcess( ) , PVOID(context . Esp) , 

NT: :MemoryBasicInformation, &mbi, sizeof mbi, 0); 

NT: :USER_STACK stack = {0, 0, PCHAR(mbi.BaseAddress) + mbi.RegionSize, 
mbi.BaseAddress, mbi.AllocationBase} ; 



NT: :CLIENT_ID cid; 

NT: :ZwCreateThread(&hThread, THREAD_ALL_ACCESS , &oa, 
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hProcess, &cid, &context, &stack, TRUE); 

NT: :THREAD_BASIC_INFORMATION tbi; 

NT : :ZwQueryInformationThread(NtCurrentThread( ) , 

NT : :ThreadBasicInformation, 

&tbi, sizeof tbi, 0) ; 

NT::PNT_TIB tib = tbi.TebBaseAddress; 

NT : :ZwQueryInformationThread(hThread, NT : :ThreadBasicInformation, 

&tbi, sizeof tbi, 0) ; 

NT : :ZwWriteVirtualMemory (hProcess, tbi.TebBaseAddress, 

&tib->ExceptionList , sizeof tib->ExceptionList , 
0 ); 

InformCsrss(hProcess, hThread, 

ULONG(cid.UniqueProcess) , ULONG(cid.UniqueThread) ) ; 

NT: :ZwResumeThread (hThread, 0); 

NT : :ZwClose( hThread) ; 

NT : :ZwClose(hProcess) ; 

return int(cid.UniqueProcess) ; 

} 

#pragma optimize ( " " , on ) 



int main() 

{ 

int n = fork( ) ; 

Sleep(n * 10) ; 

Beep(100, 100); 
printf ( "%d\n" , n); 
return 0; 

} 

There is much about Example 6.1 that needs explaining. The main part of the exam- 
ple implements a fork library routine that is exercised by the function main. 

main first tries to report the success or failure of the fork using the minimum of func- 
tionality by beeping the system beeper; if the fork is successful, two beeps should be 
heard, main then tries to print the return value of fork on its standard output, which 
requires communication with the Win32 subsystem process (csrss.exe) if the standard 
output is a console. 

The following steps are taken by the fork routine to make a copy of the current 
process: 

■ Mark all the open handles of the process as inheritable. Typically, neither the han- 
dles created explicitly by a Win32 program, nor the handles created implicitly by 
Win32 DLLs such as kernel32.dll are marked as inheritable. 

■ Call ZwCreateProcess to create the process. If this call returns successfully, a new 
process has been created that shares a copy of the address space of the current 
process. 
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■ Gather the information needed by ZwCreateThread to create the initial thread in 
the process: an execution context and a stack. The execution context is obtained 
by calling ZwGetContextThread for the current thread. Although the Platform SDK 
documentation for GetThreadContext states that it is not possible to get a valid 
context for a running thread, the returned context is a good starting point and 
the most volatile members of the context are explicitly set later. The dimensions 
of the stack of the current thread are obtained by calling ZwQueryVirtualMemory. 

■ Update the Eip (instruction pointer) member of the context to point to the 
thunk (a routine named child) at which the initial thread will start running and 
then create the thread in a suspended state by calling ZwCreateThread. 

■ The calling thread may have established some frame-based exception handlers and 
the next step is to enable these in the new thread by copying the ExceptionList 
pointer from the Thread Environment Block (TEB) of the current thread to the 
TEB of new thread. 

■ InformCsrss informs the Win32 subsystem that a Win32 client process is about to 
start; this gives the subsystem the opportunity to modify some settings of the 
process, such as setting process debug and exception ports. 

■ Resume the initial thread in the forked process by calling ZwResumeThread, and 
return the process identifier of the new process to the caller. 

Inf ormCsrss just initializes a data structure and calls the routine CsrClientCallServer 
(exported by ntdll.dll) to forward the data to csrss.exe. Internally CsrClientCallServer 
uses the native LPC mechanism to convey the data. 

The initial thread in the new process starts execution at the start of the child routine. 

This declspec( naked) routine expects that a standard call frame has been established 

by fork (hence, the "#pragma optimize ( "y" , off)" to disable frame pointer omission 
for the routine fork) that enables the Esp and Ebp registers to be set with some simple 
assembly code. A zero is stored in Eax so that when the child process checks the return 
value of fork, it will find that it is zero. 

When kernel32.dll is initialized in the new process, it calls a CsrXxx routine that checks 
whether the process is connected to a subsystem and if not connects it. Unfortunately, 
the check just examines the value of a global variable and, because this variable was 
copied from the parent (along with the rest of the parents address space), it appears 
that the new process is already connected. 

There is no good solution to this problem, and the example calls a hexadecimal 
address (which varies from service pack to service pack) that is the start of the private 
routine CsrpConnectToServer; this routine connects unconditionally to the subsystem 
and updates the global variable. 

ntdll.dll exports a number of routines whose names start with Csr; the function of 
these routines is to support interaction between clients and subsystems. It is difficult to 
decide whether these routines are specific to communication with the Win32 subsys- 
tem or are intended to be used more widely. They are not used by the Posix or OS/2 
subsystems, but they are parameterized in a way that suggests generality (for example, 
the "\Windows" argument to CsrpConnectToServer, which is used to identify a named 
LPC port to which the subsystem is listening). 



1996 CH06 11.24.99 09:54 Page 165 



Processes: Example 6.2 165 

When Example 6.1 is compiled and linked, its executable file contains imports from 
two or three DLLs: ntdll.dll, kernel32.dll and possibly a C run-time library DLL. Some 
versions of msvcrt.dll (a C run-time library DLL) also have problems arising from 
global variables already having been initialized (by the parent process) before their 
DllEntry Point routine is first invoked. Statically linking to the C run-time library 
often solves this problem, but it bodes ill for the suitability of many other common 
DLLs for forking. 



Example 6.2: Creating a Win32 Process 



#include "ntdll.h" 
#include <stdio.h> 

namespace NT { 
extern "C" { 

NTSTATUS 

NTAPI 

CsrClientCallServer( 
IN PVOID Message, 
IN PVOID, 

IN ULONG Opcode, 
IN ULONG Size 
); 



} 

} 

VOID InformCsrss (HANDLE hProcess, HANDLE hThread, ULONG pid, ULONG tid) 

{ 

struct CSRSS_MESSAGE { 

ULONG Unknownl ; 

ULONG Opcode; 

ULONG Status; 

ULONG Unknown2; 



struct { 

NT : : PORT_MESSAGE PortMessage; 

CSRSS_MESSAGE CsrssMessage ; 

PR0CESS_INF0RMATI0N Processlnf ormation ; 

NT: :CLIENT_ID Debugger; 

ULONG CreationFlags; 

ULONG VdmInfo[2] ; 

} csrmsg = {{0}, {0}, {hProcess, hThread, pid, tid}, {0}, 0, {0}}; 

NT: :CsrClientCallServer(&csrmsg, 0, 0x10000, 0x24); 

} 

PWSTR CopyEnvironment (HANDLE hProcess) 

{ 

PWSTR env = GetEnvironmentStringsW( ) ; 

ULONG n; 

for (n = 0; env[n] != 0; n += wcslen(env + n) + 1) ; n *= sizeof *env; 

ULONG m = n; 

PVOID p = 0; 

NT: :ZwAllocateVirtualMemory( hProcess, &p, 0, &m, 

MEM_COMMIT, PAGE_READWRITE) ; 
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NT: :ZwWriteVirtualMemory (hProcess, p, env, n, 0); 
return PWSTR(p); 



VOID CreateProcessParameters(HANDLE hProcess, NT::PPEB Peb, 
NT: :PUNICODE_STRING ImageFile) 



{ 



NT: :PPROCESS_PARAMETERS pp; 



NT: :RtlCreateProcessParameters(&pp, ImageFile, 0, 0, 0, 0, 0, 0, 0, 0); 

pp->Environment = CopyEnvironment (hProcess) ; 

ULONG n = pp->Size; 

PVOID p = 0; 

NT: :ZwAllocateVirtualMemory( hProcess, &p, 0, &n, 

MEM_COMMIT, PAGE_READWRITE) ; 

NT: :ZwWriteVirtualMemory (hProcess, p, pp, pp->Size, 0); 

NT: :ZwWriteVirtualMemory (hProcess, PCHAR(Peb) + 0x10, &p, sizeof p, 0); 

NT : :RtlDestroyProcessParameters(pp) ; 

} 

int exec (NT : :PUNICODE_STRING name) 

{ 

HANDLE hProcess, hThread, hSection, hFile; 



NT: :OBJECT_ATTRIBUTES oa = {sizeof oa, 0, name, OBJ_CASE_INSENSITIVE} ; 

NT: : IO_STATUS_BLOCK iosb; 

NT: :ZwOpenFile(&hFile, FILE_EXECUTE j SYNCHRONIZE, &oa, &iosb, 

F I L E_S H AR E_R E AD , F I LE_SYNCHR0N0US_I0_N0NALERT ) ; 

oa.ObjectName = 0; 

NT: :ZwCreateSection(&hSection, SECTION_ALL_ACCESS, &oa, 0, 

PAGE_EXECUTE, SEC_IMAGE, hFile); 

NT : :ZwClose(hFile) ; 

NT: :ZwCreateProcess(&hProcess, PROCESS_ALL_ACCESS, &oa, 

NtCurrentProcess( ) , TRUE, hSection, 0, 0); 

NT: : SECTION_IMAGE_INFORMATION sii; 

NT : :ZwQuerySection(hSection, NT : :SectionImageInformation, 

&sii, sizeof sii, 0) ; 

NT : :ZwClose( hSection) ; 

NT : :USER_STACK stack = {0}; 

ULONG n = sii.StackReserve; 

NT: :ZwAllocateVirtualMemory ( hProcess, &stack . ExpandableStackBottom, 0, &n, 
MEM_RESERVE, PAGE_READWRITE) ; 

stack. ExpandableStackBase = PCHAR( stack. ExpandableStackBottom) 

+ sii.StackReserve; 

stack. ExpandableStackLimit = PCHAR( stack. ExpandableStackBase) 

- sii.StackCommit ; 
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n = sii.StackCommit + PAGE_SIZE; 

PVOID p = PCHAR(stack.ExpandableStackBase) - n; 

NT: :ZwAllocateVirtualMemory (hProcess, &p, 0, &n, 

MEM_COMMIT, PAGE_READWRITE) ; 



ULONG x; n = PAGE_SIZE; 

NT: :ZwProtectVirtualMemory (hProcess, &p, &n, 

PAGE_READWRITE | PAGE_GUARD, &x); 

NT:: CONTEXT context = {CONTEXT_FULL} ; 

context .SegGs = 0; 

context .SegFs = 0x38; 

context .SegEs = 0x20; 

context .SegDs = 0x20; 

context .SegSs = 0x20; 

context .SegCs = 0x18; 

context .EFlags = 0x3000; 

context. Esp = ULONG(stack.ExpandableStackBase) - 4; 
context. Eip = UL0NG(sii. EntryPoint) ; 

NT: :CLIENT_ID cid; 

NT: :ZwCreateThread(&hThread, THREAD_ALL_ACCESS , &oa, 

hProcess, &cid, &context, &stack, TRUE); 

NT: : PROCESS_BASIC_INFORMATION pbi; 

NT : :ZwQueryInformationProcess(hProcess, NT : : ProcessBasicInformation, 

&pbi, sizeof pbi, 0); 

CreateProcessParameters(hProcess, pbi.PebBaseAddress, name); 

InformCsrss(hProcess, hThread, 

ULONG(cid.UniqueProcess) , ULONG(cid.UniqueThread) ) ; 

NT: :ZwResumeThread (hThread, 0); 

NT : :ZwClose(hProcess) ; 

NT : :ZwClose( hThread) ; 

return int(cid.UniqueProcess) ; 

} 

#pragma comment (linker, " -entry :wmainCRTStartup" ) 
extern "C" 

int wmain(int argc, wchar_t *argv[]) 

{ 

NT: :UNICODE_STRING ImageFile; 

NT : :RtlInitUnicodeString(&ImageFile, argv[1 ] ) ; 

exec(&ImageFile) ; 

return 0; 

} 

Example 6.2 demonstrates how to create a process from an executable PE format file. 
The argument to the program is the full path in the native NT format of the executable 
file. To start notepad the argument could be "\SystemRoot\System32\notepad.exe". 
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The following steps are taken by the exec routine to create a new process running a 
specific image file: 

■ Open the executable file, and create an image section from it by calling 
ZwCreateSection with an argument of SEC_IMAGE. Once the section has been cre- 
ated, the file can be closed. 

■ Call ZwCreateProcess to create the process. If this call returns successfully, a new 
process has been created that has the image section and ntdll.dll mapped into its 
address space. 

■ Call ZwQuerySection to obtain information about the image, such as its entry 
point and suggested stack size. Once this information has been obtained, the sec- 
tion handle can be closed, because the section is now referenced by the new 
process. 

■ Create the user mode stack. ZwAllocateVirtualMemory is used to perform the allo- 
cations, and ZwProtectVirtualMemory is used to establish a guard page at the end 
of the committed region of the stack. 

■ Establish the execution context of the initial thread by storing fixed values into 
the CONTEXT structure and updating the stack pointer (Esp) to point to the new 
stack and the instruction pointer (Eip) to point to the entry point of the image. 
The Win32 functions CreateProcess and CreateThread set Eip to the address of a 
thunk in kernel32.dll that establishes a frame-based exception handler before 
calling the image entry point, but this example does not bother with that 
refinement. 

■ Create the initial thread in a suspended state by calling ZwCreateThread. 

■ Create and copy the process parameters (including process environment) to the 
new process and update the PEB of the new process to point to them. 

■ InformCsrss informs the Win32 subsystem that a Win32 client process is about to 
start; this gives the subsystem the opportunity to modify some settings of the 
process, such as setting process debug and exception ports. 

■ Resume the initial thread in the new process by calling ZwResumeThread. 

At any time after the creation of the process and before resuming the initial thread, the 
process parameters can be created. The process parameters contain process information 
that is maintained and manipulated in user mode such as the current directory, the 
command line, the environment, and so on. Most values can be copied from the cur- 
rent process. 

First the environment is copied to the new process, then the process parameters them- 
selves (which contain a pointer to the environment), and finally the PEB of the new 
process is patched to point to the process parameters. 
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Example 6.3: Using RtlQueryProcessDebuglnformation to 
extend ToolHelp Library Implementation 



#include "ntdll.h" 

#include <tlhelp32.h> 

#include <stdlib.h> 

#include <stdio.h> 

struct ENTRIES { 

ULONG Offset; 

ULONG Count; 

ULONG Index; 

ENTRIES() : Offset(0), Count(0), lndex(0) {} 

ENTRIES(ULONG in, ULONG n) : Offset(m), Count(n), lndex(0) {} 

}; 



enum EntryType { 

ProcessType, 

ThreadType, 

ModuleType, 

HeapType, 

MaxType 

}; 

NT: : PSYSTEM_PROCESSES GetProcessesAndThreads( ) 

{ 

ULONG n = 0x100; 

NT: :PSYSTEM_PROCESSES sp = new NT: :SYSTEM_PROCESSES[n] ; 

while (NT : : ZwQuerySystemlnf ormation ( 

NT : :SystemProcessesAndThreadsInformation, 
sp, n * sizeof *sp, 0) 

== STATUS_INFO_LENGTH_MISMATCH) 
delete [] sp, sp = new NT: :SYSTEM_PROCESSES[n = n * 2]; 
return sp; 

} 

NT: :PDEBUG_BUFFER GetModulesAndHeaps (ULONG pid, ULONG mask) 

{ 

NT: :PDEBUG_BUFFER db = NT: :RtlCreateQueryDebugBuffer(0, FALSE); 

NT: :RtlQueryProcessDebugInformation(pid, mask, db); 
return db; 

} 

ULONG ProcessCount (NT : :PSYSTEM_PROCESSES sp) 

{ 

ULONG n = 0; 
bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; ! done ; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) 
n++, done = p->NextEntryDelta == 0; 
return n; 



ULONG ThreadCount (NT : : PSYSTEM_PROCESSES sp) 

{ 

ULONG n = 0; 
bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) 
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n += p->ThreadCount, done = p->NextEntryDelta == 0; 
return n; 

} 

ULONG ModuleCount (NT: : PDEBUG_BUFFER db) 

{ 

return db->ModuleInformation ? *PULONG(db->ModuleInformation) : 0; 

} 

ULONG HeapCount (NT : : PDEBUG_BUFFER db) 

{ 

return db->HeapInformation ? *PULONG(db->HeapInformation) : 0; 

} 

VOID AddProcesses ( PPR0CESSENTRY32 pe, NT: : PSYSTEM_PROCESSES sp) 

{ 

bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) { 

pe->dwSize = sizeof *pe; 

pe->cntUsage = 0; 

pe->th32ProcessID = p->ProcessId; 

pe->th32DefaultHeapID = 0; 

pe->th32ModuleID = 0; 

pe->cntThreads = p->ThreadCount ; 

pe->th32ParentProcessID = p->InheritedFromProcessId; 

pe->pcPriClassBase = p->BasePriority ; 

pe->dwFlags = 0; 

sprintf (pe->szExeFile, *ls" , 

p->ProcessName. Length / 2, p->ProcessName. Buffer) ; 



pe++; 

done = p->NextEntryDelta == 0; 

} 

} 

VOID AddThreads ( PTHREADENTRY32 te, NT: : PSYSTEM_PROCESSES sp) 

{ 

bool done = false; 

for (NT: : PSYSTEM_PROCESSES p = sp; !done; 

p = NT : : PSYSTEM_PROCESSES ( PCHAR ( p ) + p->NextEntryDelta) ) { 

for (ULONG i = 0; i < p->ThreadCount ; i++) { 

te->dwSize = sizeof *te; 
te->cntUsage = 0; 

te->th32ThreadID = DWORD(p->Threads[i] .Clientld.UniqueThread) ; 
te->th320wnerProcessID = p->ProcessId; 
te->tpBasePri = p->Threads[i] .BasePriority; 
te->tpDeltaPri = p->Threads[i] .Priority 

- p->Threads[i] .BasePriority; 
te->dwFlags = 0; 

te++; 

} 

done = p->NextEntryDelta == 0; 

} 

} 
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VOID AddModules ( PM0DULEENTRY32 me, NT : : PDEBUG_BUFFER db, ULONG pid) 

{ 

ULONG n = ModuleCount (db) ; 

NT: :PDEBUG_MODULE_INFORMATION p 

= NT : : PDEBUG_MODULE_INFORMATION(PULONG(db->ModuleInformation) +1); 

for (ULONG i = 0; i < n; i++) { 

me->dwSize = sizeof *me; 
me->th32ModuleID = 0; 
me->th32ProcessID = pid; 
me->GlblcntUsage = p[i] . LoadCount ; 
me->ProccntUsage = p[i] . LoadCount ; 
me->modBaseAddr = PBYTE(p[i] .Base) ; 
me->modBaseSize = p[i].Size; 
me->hModule = HMODULE(p[i] .Base) ; 

sprintf (me->szModule, "%s", p[i] . ImageName + p[i] .ModuleNameOff set ) ; 
sprintf (me->szExePath, "%s", p[i] . ImageName) ; 

me++; 

} 

} 

VOID AddHeaps ( PHEAPLIST32 hi, NT: : PDEBUG_BUFFER db, ULONG pid) 

{ 

ULONG n = HeapCount (db) ; 

NT: :PDEBUG_HEAP_INFORMATION p 

= NT: :PDEBUG_HEAP_INFORMATION(PULONG(db->HeapInformation) +1); 



for (ULONG i = 0; i < n; i++) { 

hl->dwSize = sizeof *hl; 
hl->th32ProcessID = pid; 
hl->th32HeapID = p[i].Base; 
hl->dwFlags = p [ i] . Flags; 

hl++; 

} 

} 

template<class T> 

BOOL GetEntry (HANDLE hSnapshot, T entry, bool first, EntryType type) 

{ 

ENTRIES *entries = ( ENTRIES* )MapViewOf File( hSnapshot , FILE_MAP_WRITE, 

0 , 0 , 0 ); 

if (entries == 0) return FALSE; 

BOOL rv = TRUE; 

entries[type] . Index = first ? 0 : entries[type] . Index + 1; 

if (entries[type] . Index >= entries[type] .Count ) 

SetLastError (ERROR_NO_MORE_FILES) , rv = FALSE; 
if (entry->dwSize < sizeof *entry) 

SetLastError (ERROR_INSUFFICIENT_BUFFER) , rv = FALSE; 
if (rv) 

*entry = T(PCHAR( entries) 

+ entries[type] .Offset) [entries[type] . Index] ; 
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UnmapViewOf File(entries) ; 
return rv; 



HANDLE 

WINAPI 

CreateToolhelp32Snapshot (DWORD flags, DWORD pid) 

{ 

if (pid == 0) pid = GetCurrentProcessId() ; 

ULONG mask = ((flags & TH32CS_SNAPM0DULE) ? PDI_MODULES : 0) j 
((flags & TH32CS_SNAPHEAPLIST) ? PDI_HEAPS : 0); 

NT: :PDEBUG_BUFFER db = 

(flags & (TH32CS_SNAPM0DULE | TH32CS_SNAPHEAPLIST) ) 

? GetModulesAndHeaps(pid, mask) : 0; 

NT: :PSYSTEM_PROCESSES sp = 

(flags & (TH32CS_SNAPPR0CESS | TH32CS_SNAPTHREAD) ) 

? GetProcessesAndThreads( ) : 0; 

ENTRIES entries[MaxType] ; 

ULONG n = sizeof entries; 

if (flags & TH32CS_SNAPPR0CESS ) { 

entries[ProcessType] = ENTRIES(n, ProcessCount (sp) ) ; 
n += entries[ProcessType] .Count * sizeof (PR0CESSENTRY32) ; 

} 

if (flags & TH32CS_SNAPTHREAD ) { 

entries[ThreadType] = ENTRIES(n, ThreadCount (sp) ) ; 
n += entries[ThreadType] .Count * sizeof (THREADENTRY32) ; 

} 

if (flags & TH32CS_SNAPM0DULE ) { 

entries[ModuleType] = ENTRIES(n, ModuleCount (db) ) ; 
n += entries[ModuleType] .Count * sizeof (M0DULEENTRY32) ; 

} 

if (flags & TH32CS_SNAPHEAPLIST) { 

entries[HeapType] = ENTRIES(n, HeapCount (db) ) ; 
n += entries[HeapType] .Count * sizeof (HEAPLIST32) ; 

} 

SECURITY_ATTRIBUTES sa = {sizeof sa, 0, (flags & TH32CS_INHERIT) != 0}; 

HANDLE hMap = CreateFileMapping ( HANDLE (0XFFFFFFFF) , &sa, 

PAG E_R E ADWR I T E j SEC_COMMIT, 0, n, 0); 

ENTRIES *p = ( ENTRIES* )MapViewOfFile( hMap, FILE_MAP_WRITE, 0, 0, 0); 

for (int i = 0; i < MaxType; i++) p[i] = entries[i]; 

if (flags & TH32CS_SNAPPR0CESS ) 

AddProcesses(PPR0CESSENTRY32(PCHAR(p) + entries[ProcessType] .Offset) , 

sp) ; 

if (flags & TH32CS_SNAPTHREAD ) 

AddThreads ( PTHREADENTRY32 ( PCHAR ( p ) + entries[ThreadType] .Offset) , 

sp) ; 

if (flags & TH32CS_SNAPM0DULE ) 

AddModules ( PM0DULEENTRY32 ( PCHAR ( p ) + entries[ModuleType] .Offset) , 
db, pid); 

if (flags & TH32CS_SNAPHEAPLIST) 

AddHeaps ( PHEAPLIST32 ( PCHAR ( p ) + entries[HeapType] .Off set) , 
db, pid); 
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UnmapViewOf File(p) ; 
if (sp) delete [] sp; 

if (db) NT: : RtlDestroyQueryDebugBuff er(db) ; 
return hMap; 

} 

BOOL 

WINAPI 

Process32First (HANDLE hSnapshot, PPR0CESSENTRY32 pe) 

{ 

return GetEntry (hSnapshot , pe, true, ProcessType) ; 

} 

BOOL 

WINAPI 

Process32Next (HANDLE hSnapshot, PPR0CESSENTRY32 pe) 

{ 

return GetEntry (hSnapshot , pe, false, ProcessType); 

} 

BOOL 

WINAPI 

Thread32First (HANDLE hSnapshot, PTHREADENTRY32 te) 

{ 

return GetEntry (hSnapshot , te, true, ThreadType); 

} 

BOOL 

WINAPI 

Thread32Next( HANDLE hSnapshot, PTHREADENTRY32 te) 

{ 

return GetEntry (hSnapshot , te, false, ThreadType); 

} 

BOOL 

WINAPI 

Module32First (HANDLE hSnapshot, PM0DULEENTRY32 me) 

{ 

return GetEntry (hSnapshot , me, true, ModuleType); 

} 

BOOL 

WINAPI 

Module32Next( HANDLE hSnapshot, PM0DULEENTRY32 me) 

{ 

return GetEntry (hSnapshot , me, false, ModuleType); 

} 

BOOL 

WINAPI 

Heap32ListFirst (HANDLE hSnapshot, PHEAPLIST32 hi) 

{ 

return GetEntry (hSnapshot , hi, true, HeapType); 

} 

BOOL 

WINAPI 

Heap32ListNext (HANDLE hSnapshot, PHEAPLIST32 hi) 

{ 

return GetEntry (hSnapshot , hi, false, HeapType); 

} 
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Example 6.3 extends Example 1.1 in Chapter 1, “System Information and Control,” to 
provide support for retrieving module and heap information. The code implements 
ANSI (rather than Unicode) versions of the routines and, apart from the routines to 
implement enumerating heap entries, is an almost complete implementation of the 
ToolHelp library. 
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The system services described in this chapter create and manipulate job objects. Job 
objects are only available in Windows 2000. 



ZwCreateJobObject 



ZwCreateJobObject creates or opens a job object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateJobObject ( 

OUT PHANDLE JobHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 



Parameters 

JobHandle 

Points to a variable that will receive the job object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the job object. This parameter 
can be zero, or any combination of the following flags: 



J 0B_0BJ ECT_ASS IGN_PR0CESS 
J 0B_0BJ ECT_SET_ATTR I BUTES 
J0B_0BJECT_QUERY 
J0B_0BJ EXTERMINATE 
JOB_OBJECT_SET_SECURITY_ATTRIBUTES 
J0B_0BJECT ALL_ACCESS 



Add process to job 
Set job attributes 
Query job attributes 
Terminate job 

Set job security attributes 
All of the preceding + 
STANDARD_RIGHTS_ALL 



Obj ectAttributes 

Points to a structure that specifies the objects attributes. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 



Related Win32 Functions 

CreateJobObject. 

Remarks 

The routine ZwCreateJobObject is only present in Windows 2000. 



ZwOpenJobObject 



ZwOpenJobObject opens a job object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

Zw0penJob0bject( 

OUT PHANDLE JobHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 



Parameters 

JobHandle 

Points to a variable that will receive the job object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the job object. This parameter 
can be zero, or any combination of the following flags: 



J0B_0BJECT_ASSIGN_PR0CESS 
J0B_0BJ ECT_SET_ATTR I BUTES 
J 0B_0B J ECT_QU E R Y 
J0B_0BJ ECT _TERM I NATE 
JOB_OBJECT_SET_SECURITY_ATTRIBUTES 
J0B_0BJECT_ALL_ACCESS 



Add process to job 
Set job attributes 
Query job attributes 
Terminate job 

Set job security attributes 
All of the preceding + 
STANDARD_RIGHTS_ALL 



Obj ectAttributes 

Points to a structure that specifies the objects attributes. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

OpenJobObject. 

Remarks 

The routine ZwOpenJobObject is only present in Windows 2000. 
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ZwTerminateJobObject 



ZwTerminateJobObject terminates a job and the processes and threads that it contains. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwTerminateJobObject ( 

IN HANDLE JobHandle, 

IN NTSTATUS ExitStatuS 

); 



Parameters 

JobHandle 

A handle to a job object. The handle must grant JOB_OBJECT_TERMINATE access. 

ExitStatus 

Specifies the exit status for all processes and terminated as a result of this call. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

TerminateJobObj ect. 

Remarks 

TerminateJobObj ect exposes the full functionality of ZwTerminateJobObject. 
The routine ZwTerminateJobObject is only present in Windows 2000. 



ZwAssignProcessToJobObject 



ZwAssignProcessToJobObject associates a process with a job. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAssignProcessToJobObject ( 

IN HANDLE JobHandle, 

IN HANDLE ProcessHandle 

); 



Parameters 

JobHandle 

A handle to a job object. The handle must grant JOB_OBJECT_ASSIGN_PROCESS access. 

ProcessHandle 

A handle to a process object. The handle must grant PROCESS_SET_QUOTA and 
PROCESS TERMINATE access. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_PROCESS_IS_TERMINATING. 

Related Win32 Functions 

AssignProcessToJobObj ect. 

Remarks 

AssignProcessToJobObj ect exposes the full functionality of 

ZwAssignProcessToJobObject. 

The routine ZwAssignProcessToJobObject is only present in Windows 2000. 



ZwQuerylnformationJobObject 



ZwQuerylnformationJobObject retrieves information about a job object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationJobObject ( 

IN HANDLE JobHandle, 

IN JOBOBJECTINFOCLASS Joblnf ormationClass , 

OUT PVOID Joblnformation, 

IN ULONG JoblnformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

JobHandle 

A handle to a job object. The handle must grant J0B_0BJECT_QUERY access. 

Joblnf ormation Class 

Specifies the type of job information to be queried. The permitted values are drawn 
from the enumeration JOBOBJECTINFOCLASS, described in the following section. 

Joblnf ormation 

Points to a caller-allocated buffer or variable that receives the requested job 
information. 

JoblnformationLength 

Specifies the size in bytes of Joblnformation, which the caller should set according to 
the given JoblnformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Joblnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, STATUS_INFO_LENGTH_MISMATCH, or 
STATUS_BUFFER_OVERFLOW. 

Related Win32 Functions 

QuerylnformationJobOb j ect. 

Remarks 

QuerylnformationJobOb] ect exposes the full functionality of 

ZwQuerylnformationJobOb ject. 

The routine ZwQuerylnformationJobOb ject is only present in Windows 2000. 



ZwSetlnformationJobObject 



ZwSetlnformationJobObject sets information affecting a job object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationJobObject ( 

IN HANDLE JobHandle, 

IN J0B0BJECTINF0CLASS Joblnf ormationClass , 

IN PVOID Joblnformation, 

IN ULONG JoblnformationLength 

); 



Parameters 

JobHandle 

A handle to a job object. The handle must grant JOB_OBJECT_SET_ATTRIBUTES access. 
Some information classes also require JOB_OBJECT_SET_SECURITY_ATTRIBUTES access. 

Joblnformation Class 

Specifies the type of job information to be set. The permitted values are drawn from 
the enumeration JOBOBJECTINFOCLASS, described in the following section. 

Joblnformation 

Points to a caller-allocated buffer or variable that contains the job information to 
be set. 

JoblnformationLength 

Specifies the size in bytes of Joblnformation, that the caller should set according to the 
given JoblnfonmationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 
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Related Win32 Functions 

Set Inf ormationJobObj ect. 



Remarks 

Set Inf ormationJobObj ect exposes the full functionality of ZwSetlnformationJobObject. 
The routine ZwSetlnformationJobObject is only present in Windows 2000. 



JOBOBJECTINFOCLASS 






typedef enum _J0B0BJECTINF0CLASS { 


Query 


Set 


JobObjectBasicAccountinglnformation = 1, 


II Y 


N 


JobObjectBasicLimit Informat ion, 


// Y 


Y 


JobObjectBasicProcessIdList , 


// Y 


N 


JobObjectBasicUIRest riot ions, 


// Y 


Y 


JobObjectSecurityLimit Informat ion, 


// Y 


Y 


JobObjectEndOf JobTimelnformation, 


// N 


Y 


JobObjectAssociateCompletionPort Informat ion, 


// N 


Y 


JobObjectBasicAndloAccountinglnformation, 


// Y 


N 


JobObj ect ExtendedLimit Informat ion 
} JOBOBJECTINFOCLASS; 


// Y 


Y 


JobObjectBasicAccountinglnformation 





typedef struct _J0B0BJECT_BASIC_ACC0UNTING_INF0RMATI0N { 

LARGE_INTEGER TotalUserTime ; 

LARGE_INTEGER TotalKernelTime ; 

LARGE_INTEGER ThisPeriodTotalUserTime; 

LARGE_INTEGER ThisPeriodTotalKernelTime ; 

ULONG TotalPageFaultCount ; 

ULONG TotalProcesses; 

ULONG ActiveProcesses; 

ULONG TotalTerminatedProcesses; 

} J0B0BJECT_BASIC_ACC0UNTING_INF0RMATI0N , 

*PJ0B0BJECT_BASIC_ACC0UNTING_INF0RMATI0N ; 

Members 

TotalUserTime 

The total time spent executing in user mode, measured in units of 100-nanoseconds, 
of all the threads that ever belonged to the job. 

To ta l Kernel T ime 

The total time spent executing in kernel mode, measured in units of 100-nanoseconds, 
of all the threads that ever belonged to the job. 

ThisPeriodTotalUserTime 

The total time spent executing in user mode, measured in units of 100-nanoseconds, 
of all the threads that ever belonged to the job since the user mode execution time 
limit was last set. 
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ThisPeriodTotalKernel Time 

The total time spent executing in kernel mode, measured in units of 100-nanoseconds, 
of all the threads that ever belonged to the job since the kernel mode execution time 
limit was last set. 

TotalPageFaultCount 

The total number of page faults incurred by all processes that ever belonged to 
the job. 

TotalProcesses 

The total number of processes that ever belonged to the job. 

ActiveProcesses 

The number of processes that currently belong to the job. 

TotalTerminatedProcesses 

The total number of processes that have been terminated because a job limit was 
exceeded. 

Remarks 

JOBOBJECT_BASIC_ACCOUNTING_INFORMATION is identical to the structure of the same 
name used by the Win32 function, QuerylnformationJobObject. 



JobObjectBasicLimitlnformation 



typedef Struct _J0B0BJ ECT_BAS I C_LIMIT_IN FORMATION { 

LARGE_INTEGER PerProcessUserTimeLimit ; 

LARGE_INTEGER PerJobUserTimeLimit ; 

ULONG LimitFlags; 

ULONG MinimumWorkingSetSize; 

ULONG MaximumWorkingSetSize; 

ULONG ActiveProcessLimit ; 

ULONG Affinity; 

ULONG PriorityClass; 

ULONG SchedulingClass; 

} JOBOBJECT_BASIC_LI MISINFORMATION, *PJOBOBJECT_BASIC_LIMIT_INFORMATION; 

Members 

PerProcess UserTimeLimit 

The limit on the time spent executing in user mode, measured in units of 100-nanosec- 
onds, of all the threads in any one process belonging to the job. When setting limits, this 
member is ignored unless LimitFlags specifies JOB_OBJECT_LIMIT_PROCESS_TIME. 

Perjob UserTimeLimit 

The limit on the time spent executing in user mode, measured in units of 100- 
nanoseconds, of the job. When setting limits, this member is ignored unless LimitFlags 
specifies JOB_OBJECT_LIMIT_JOB_TIME. When querying limits, the value is the total time 
allowed to all threads that ever belonged to the job; subtracting TotalUserTime (from 
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JOBOBJECT_BASIC_ACCOUNTING_INFORMATION) gives the remaining time. When setting 
limits the value is the time remaining until the job user mode execution time limit is 
reached. 



LimitFlags 

Specifies which limits are in force. When setting limits, if a limit is not specified as 
being in force, the value of its member in the limit structure is ignored. Some limit 
flags are only valid when specified in conjunction with a 
JOBOBJECT_EXTENDED_L I MISINFORMATION structure. 



JOB_OBJECT_LIMIT_WORKINGSET 0x0001 
JOB_OBJECT_LIMIT_PROCESS_TIME 0x0002 
JOB_OBJECT_LIMIT_JOB_TIME 0x0004 
JOB_OBJECT_LIMIT_ACTIVE_PROCESS 0x0008 
JOB_OBJECT_LIMIT_AFFINITY 0x0010 
JOB_OBJECT_LIMIT_PRIORITY_CLASS 0x0020 
JOB_OBJECT_LIMIT_PRESERVE_JOB_TIME 0x0040 
JOB_OBJECT_LIMIT_SCHEDULING_CLASS 0x0080 
JOB_OBJECT_LIMIT_PROCESS_MEMORY 0x0100 
J0B_0BJECT_LIMIT_J0B_MEM0RY 0X0200 
JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION 0x0400 
J 0B_0B J ECT_BR EAKAWAY_OK 0x0800 
JOB_OBJECT_SILENT_BREAKAWAY 0x1 000 



Minimum WorkingSetSize 

The minimum working set size, in bytes, for all processes belonging to the job. When 
setting limits, this member is ignored unless LimitFlags specifies 
JOB_OBJECT_LIMIT_WORKINGSET. 

Maximum WorkingSetSize 

The maximum working set size, in bytes, for all processes belonging to the job. When 
setting limits, this member is ignored unless LimitFlags specifies 
JOB_OBJECT_LIMIT_WORKINGSET. 

Affinity 

The processor affinity for all processes belonging to the job. When setting limits, this 
member is ignored unless LimitFlags specifies JOB_OBJECT_LIMIT_AFFINITY. 



PriorityClass 

The priority class for all processes belonging to the job. When setting limits, this mem- 
ber is ignored unless LimitFlags specifies JOB_OBJECT_LIMIT_PRIORITY_CLASS.The 
defined priority classes include: 



PC_IDLE 1 
PC_N0RMAL 2 
PC_HIGH 3 
PC_REALTIME 4 



PC_BEL0W_N0RMAL 5 
PC_AB0VE_N0RMAL 6 

SelncreaseBasePriorityPrivilege is required to set PriorityClass to PC_REALTIME. 
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SchedulingClass 

The scheduling class for all processes belonging to the job. When setting limits, this 
member is ignored unless LimitFlags specifies JOB_OBJECT_LIMIT_SCHEDULING_CLASS. 
The scheduling class affects the thread scheduling quantum: the higher the class the 
longer the quantum. The permitted values range from zero to nine; 
SelncreaseBasePriorityPrivilege is required to set SchedulingClass to values greater 
than five. 

Remarks 

J OBOB J ECT_BAS I C_L I M I T_I N FORMAT ION is identical to the structure of the same name 
used by the Win32 functions QuerylnformationJobObject and 

Setlnf ormationJobObj ect. However the PriorityClass field is encoded differently: the 
Win32 functions use the XXX_PRIORITY_CLASS values defined in winbase.h. 

Although JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION, JOB_OBJECT_BREAKAWAY_OK 
and JOB_OBJECT_SILENT_BREAKAWAY are not associated with any particular member of 
JOBOBJECT_EXTENDED_LI MISINFORMATION, they are only valid when specified with the 
information class JobObj ectExtendedLimitlnformation. 

The breakaway flags JOB_OBJECT_BREAKAWAY_OK and J 0B_0 B J E CT_S I L E N T_B R E AKAWAY 
determine whether new processes created by members of the job can be disassociated 
from the job. JOB_OBJECT_SILENT_BREAKAWAY means that the disassociation is automatic 
whilst JOB_OBJECT_BREAKAWAY_OK means that the creator of a new process can request 
that it be disassociated when calling ZwCreateProcess. 



JobObjectBasicProcessIdList 



typedef struct _JOBOBJECT_BASIC_PROCESS_ID_LIST { 

ULONG NumberOfAssignedProcesses; 

ULONG NumberOf ProcessIdsInList ; 

UL0NG_PTR ProcessIdList[1 ] ; 

} J OBOB J ECT_BAS I C_PROCESS_I D_L 1ST, * P J OBOB J ECT_BAS I C_PROCESS_I D_L I ST ; 

Members 

NumberOfAssignedProcesses 

The number of active processes belonging to the job. 

Nu mberOfProcessIdsInLis t 

The number of process identifiers in the ProcessIdList array. If 

ZwQuerylnf ormationJobObj ect fails with STATUS_BUFFER_OVERFLOW, ProcessIdList con- 
tains a subset of the process identifiers belonging to the job. 

ProcessIdList 

An array of the process identifiers of the processes belonging to the job. 

Remarks 

JOBOBJECT_BASIC_PROCESS_ID_LIST is identical to the structure of the same name used 
by the Win32 function QuerylnformationJobObject. 
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JobObj ectB asicUIRestrictions 



typedef struct _J0B0BJECT_BASIC_UI_RESTRICTI0NS { 

ULONG UIRestrictionsClass; 

} JOBOBJ ECT_BASIC_UI_RESTRICTIONS, *PJ0B0BJECT_BASIC_UI_RESTRICTI0NS; 

Members 



UIRestrictionsClass 

Specifies restrictions on the user interface behavior of processes belonging to the job. 
The following restrictions are defined: 



JOB_OBJECT_UILIMIT_HANDLES 0x0001 
J0B_0BJECT_UILIMIT_READCLIPB0ARD 0x0002 
J0B_0BJECT_UILIMIT_WRITECLIPB0ARD 0x0004 
JOB_OBJECT_UILIMIT_SYSTEMPARAMETERS 0x0008 
JOB_OBJECT_UILIMIT_DISPLAYSETTINGS 0x001 0 
J0B_0BJECT_UILIMIT_GL0BALAT0MS 0x0020 
J0B_0BJECT_UILIMIT_DESKT0P 0x0040 
J0B_0BJECT_UILIMIT EXITWINDOWS 0x0080 



Remarks 

JOBOBJECT_BASIC_UI_RESTRICTIONS is identical to the structure of the same name used 
by the Win32 functions QuerylnformationJobObject and Setlnf ormationJobObj ect. 



JobObjectSecurityLimitlnformation 



typedef struct _J0B0BJECT_SECURITY_LIMIT_INF0RMATI0N { 
ULONG SecurityLimitFlags; 

HANDLE JobToken; 

PT0KEN_GR0UPS SidsToDisable; 

PT0KEN_PRI VI LEGES PrivilegesToDelete ; 

PT0KEN_GR0UPS RestrictedSids ; 

} JOBOBJ ECT_SECURITY_LIMIT_INFORMATION , 
*PJ0B0BJECT_SECURITY_LIIVIIT_INF0RMATI0N ; 



Members 



SecurityLimitFlags 

Specifies restrictions on the tokens of processes belonging to the job. The following 
restrictions are defined: 



J 0B_0B J ECT_SECUR ITY_N0_ADM I N 0x0001 
JOB_OBJECT_SECURITY_RESTRICTED_TOKEN 0x0002 
J0B_0BJECT_SECURITY_0NLY_T0KEN 0x0004 
J0B_0BJECT SECURITY FILTER_T0KENS 0x0008 



JobToken 

A handle to a token object. The handle must grant TOKEN_ASSIGN_PRIMARY, 
TOKEN_DUPLICATE, and T0KEN_IMPERS0NATE access. SeAssignPrimaryTokenPrivilege is 
required unless the token is a filtered copy of the token of the current process. When 
setting limits, this member is ignored unless SecurityLimitFlags specifies 
JOB OBJECT SECURITY ONLY TOKEN. 
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SidsToDisable 

A pointer to a T0KEN_GR0UPS structure specifying the groups to be converted to deny- 
only groups in the tokens of processes added to the job. When setting limits, this 
member is ignored unless SecurityLimitFlags specifies 
JOB_OBJECT_SECURITY_FILTER_TOKENS. 

Privileges ToDelete 

A pointer to a TOKEN_PRIVI LEGES structure specifying the privileges to be deleted from 
the tokens of processes added to the job. When setting limits, this member is ignored 
unless SecurityLimitFlags specifies JOB_OBJECT_SECURITY_FILTER_TOKENS. 

Restricted Sids 

A pointer to a TOKEN_GROUPS structure that specifies the restricted groups to be added 
to the tokens of processes added to the job. When setting limits, this member is 
ignored unless SecurityLimitFlags specifies JOB_OBJECT_SECURITY_FILTER_TOKENS. 

Remarks 

JOBOBJECT_SECURITY_LIMIT_INFORMATION is identical to the structure of the same name 
used by the Win32 functions QuerylnformationJobObject and SetlnformationJobObject. 

When querying JobObj ectSecurityLimitlnformation, enough space must be allocated 
to hold the JOBOBJ ECT_SECURITY_LIMIT_INFORMATION structure and the referenced privi- 
leges and groups. The ReturnLength information only indicates that the size of the 
JOBOBJECT_SECURITY_L I MISINFORMATION structure has been copied to the 
Joblnf ormation buffer — this is a minor bug. If a job token is set, its value cannot be 
retrieved by querying this information class. 



JobObj cctEndOfJobTimcInformation 



typedef Struct _J° B 0 B J E CT_END_OF_JOB_TIME_INFORMATION ^ 

ULONG EndOf JobTimeAction; 

} jobobject_end_of_job_time_information 3 

*PJ0B0BJECT_END_0F_J0B_TIME_INF0RMATI0N; 

Members 

EndOfjobTimeAction 

Specifies the action to be taken when the PerJobUserTimeLimit is reached. The follow- 
ing actions are defined: 

JOB_OBJECT_TERMINATE_AT_END_OF_JOB 0 
J0B_0BJECT_P0ST_AT_END_0F_J0B 1 

Remarks 

JOBOBJECT_END_OF_JOB_TIME_INFORMATION is identical to the structure of the same name 
used by the Win32 functions QuerylnformationJobObject and SetlnformationJobObject. 
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JobObjectAssociateCompletionPortlnformation 



typedef struct _J0B0BJECT_ASS0CIATE_C0MPLETI0N_P0RT { 

PVOID CompletionKey; 

HANDLE CompletionPort ; 

} J0B0BJECT_ASS0CIATE_C0MPLETI0N_P0RT, *PJ0B0BJECT_ASS0CIATE_C0MPLETI0N_P0RT; 

Members 

CompletionKey 

The value to be used as the CompletionKey argument to ZwSetloCompletion when 
messages are sent on behalf of the job. 

CompletionPort 

The handle to be used as the IoCompletionHandle argument to ZwSetloCompletion 
when messages are sent on behalf of the job. The handle must grant 
IO_COMPLETION_MODIFY_STATE access. 

Remarks 

JOBOBJECT_ASSOCIATE_COMPLETION_PORT is identical to the structure of the same name 
used by the Win32 functions QuerylnformationJobObject and SetlnformationJobObject. 

The job sends messages to the completion port when certain events occur. After call- 
ing ZwRemoveloCompletion to retrieve a message, the type of event is available in the 
Information member of the I0_STATUS_BL0CK pointed to by the IoStatusBlock argu- 
ment. The following types of events are defined: 



J 0B_0B J ECT_MSG_EN D_0 F_J 0B_T I ME 1 
JOB_OBJECT_MSG_END_OF_PROCESS_TIME 2 
J 0B_0BJ ECT_MSG_ACT I V E_P R0CESS_L I M I ' T 3 
J 0B_0BJ ECT_MSG_ACT I VE_PR0CESS_ZER0 4 
JOB_OBJECT_MSG_NEW_PROCESS 6 
JOB_OBJECT_MSG_EXIT_PROCESS 7 
JOB_OBJECT_MSG_ABNORMAL_EXIT_PROCESS 8 
JOB_OBJECT_MSG_PROCESS_MEMORY_LIMIT 9 
J 0B_0B J ECT_MSG_J 0B_M EMOR Y_L I M I T 1 0 



Depending upon the event type, the variable pointed to by the CompletionValue argu- 
ment to ZwRemoveloCompletion may contain the process identifier of the process within 
the job that caused the event. 



JobObjectBasicAndloAccountinglnformation 



typedef struct JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION { 
JOBOBJECT_BASIC_ACCOUNTING_INFORMATION Basiclnfo; 
I0_C0UNTERS Iolnfo; 

} JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION, 

* P J OBOB J ECT_BAS I C_AN D_1 0_ACC0UNT I NG_I N FORMAT I ON ; 
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Members 

Basiclnfo 

A JOBOBJ ECT_BAS I C_ACCOUNT I NG_I N FORMAT ION structure that contains the basic account- 
ing information for the job. 

Iolllfo 

An I0_C0UNTERS structure that contains the I/O accounting information for the job 

Remarks 

JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION is identical to the structure of the 
same name used by the Win32 function QuerylnformationJobObject. 



JobObjectExtendedLimitlnformation 



typedef Struct _JOBOBJECT_EXTENDED_LIMIT_INFORMATION { 

JOBOBJ ECT_BAS I C_L I MISINFORMATION BasicLimitlnf ormation ; 

I0_C0UNTERS Iolnfo; 

ULONG ProcessMemoryLimit ; 

ULONG JobMemoryLimit ; 

ULONG PeakProcessMemoryUsed; 

ULONG PeakJobMemoryUsed; 

} JOBOBJ ECT_EXTENDED_LIMIT_INFORMATION, 

*PJOBOBJECT_EXTENDED_LIMIT_INFORMATION ; 

Members 

BasicLimitlnf ormation 

A JOBOBJ ECT_BAS I C_LIM I T_IN FORMAT ION structure that specifies the basic limits for 
the job. 

Iolllfo 

An I0_C0UNTERS structure. Not currently used. 

ProcessMemoryLimit 

The maximum amount of committed virtual memory, in bytes, for any processes 
belonging to the job. When setting limits, this member is ignored unless 
BasicLimitlnf ormation . LimitFlags specifies JOB_OBJECT_LIMIT_PROCESS_MEMORY. 

Jo bMei n or y Li m i t 

The maximum amount of committed virtual memory, in bytes, for all processes 
belonging to the job. When setting limits, this member is ignored unless 
BasicLimitlnf ormation . LimitFlags specifies JOB_OBJECT_LIMIT_JOB_MEMORY. 

PeakProcessMemoryUsed 

The peak amount of virtual memory committed by any process that ever belonged to 
the job. This member cannot be set. 
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PeakJobMemoryUsed 

The peak amount of virtual memory committed by all process belonging to the job. 
This member cannot be set. 

Remarks 

JOBOBJECT_EXTENDED_LI MISINFORMATION is identical to the structure of the same name 
used by the Win32 functions Querylnf ormationJobObj ect and SetlnformationJobObject. 
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Tokens 



The system services described in this chapter create and manipulate token objects. 
Token objects are objects that encapsulate the privileges and access rights of an agent 
(a thread or process). 






ZwCreateToken creates a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateToken( 

OUT PHANDLE TokenHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN T0KEN_TYPE Type, 

IN PLUID Authenticationld, 

IN PLARGE_INTEGER ExpirationTime , 

IN PTOKEN_USER User, 

IN PT0KEN_GR0UPS Groups, 

IN PTOKEN_PRI VI LEGES Privileges, 

IN PT0KEN_0WNER Owner, 

IN PTOKEN_PRIMARY_GROUP PrimaryGroup , 

IN PTOKEN_DEFAULT_DACL DefaultDacl, 

IN PT0KEN_S0URCE Source 

); 

Parameters 

TokenHandle 

Points to a variable that will receive the token object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the token object. This parameter 
can be zero, or any combination of the following flags: 




TOKEN_ASSIGN_PRIMARY 

TOKEN_DUPLICATE 

TOKEN_IMPERSONATE 

TOKEN_QUERY 



Can be assigned as primary token 
Can be duplicated 

Can be assigned as impersonation token 
Can be queried 
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T0KEN_QUERY_S0URCE 
TOKEN_ADJUST_PRIVILEGES 
T0KEN_ADJ UST_GR0UPS 
TOKEN_ADJUST_DEFAULT 
T0KEN_ADJ UST_SESS I ON I D 
TOKEN_ALL_ACCESS 



Can be queried for source 

Token privileges can be adjusted 

Token groups can be adjusted 

Token default ACL and owner can be adjusted 

Token session id can be adjusted 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a token object. 

Token Type 

Specifies the type of token object to be created. The permitted values are drawn from 
the enumeration TOKEN_TYPE: 

typedef enum _T0KEN_TYPE { 

TokenPrimary = 1 , 

Tokenlmpersonation 
} T0KEN_TYPE, *PT0KEN_TYPE; 

Authenticationld 

Points to a structure that specifies the value that is used to correlate the token with 
other authentication information. 

Expiration Time 

Points to a structure that specifies the time at which the token will expire in the stan- 
dard time format (that is, the number of 100-nanosecond intervals since January 1, 
1601). An expiration time value of— 1 indicates that the token does not expire. 

User 

Points to a structure that specifies which user the token will represent. 

Groups 

Points to a structure that specifies to which groups the user represented by the token 
will belong. 

Privileges 

Points to a structure that specifies which privileges are granted to the user that the 
token will represent. 

Owner 

Points to a structure that specifies the default owner for objects created by the user 
which the token will represent. 

Primary Group 

Points to a structure that specifies the default group for objects created by the user that 
the token will represent. 
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DefaultDacl 

Points to a structure that specifies the default ACL for objects created by the user that 
the token will represent. 

Source 

Points to a structure that identifies the creator of the token. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_OWNER, 
STATUS_BAD_IMPERSONATION_LEVEL, STATUS_NO_SUCH_LOGON_SESSION, or 
STATUS_P R I V I L EGE_N0T_H E LD . 

Related Win32 Functions 

None. 

Remarks 

SeCreateTokenPrivilege is required to create a token. 

The Authenticationld parameter should correspond to a Local Security Authority 
(LSA) “Logon Session” identifier. This provides the link to credential information. If 
the credentials for a user are not available or not required (as when the token will only 
be used to access resources local to the system), Authenticationld could be specified 
as SYSTEM_LUID (defined in winnt.h) or copied from the process’s current token. In 
Windows 2000, the Authenticationld AN0NYM0US_L0G0N_LUID could also be used. 

TOKEN_ADJUST_SESSIONID is only valid inWindows 2000. 

Example 8.1 creates a token that is used as an argument to CreateProcessAsUser. 



ZwOpenProcessToken 



ZwOpenProcessToken opens the token of a process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenProcessToken ( 

IN HANDLE ProcessHandle , 

IN ACCESS_MASK DesiredAccess , 

OUT PHANDLE TokenHandle 

); 



Parameters 

ProcessHandle 

A handle to a process object. The handle must grant PR0CESS_QUERY_INF0RMATI0N 



access. 
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DesiredAccess 

Specifies the type of access that the caller requires to the token object. This parameter 
can be zero, or any combination of the following flags: 



TOKEN_ASSIGN_PRIMARY 

TOKEN_DUPLICATE 

T0KEN_IMPERS0NATE 

TOKEN_QUERY 

TOKEN_QUERY_SOURCE 

T0KEN_ADJ UST_PR I VI LEGES 

T0KEN_ADJ UST_GR0UPS 

TOKEN_ADJUST_DEFAULT 

T0KEN_ADJ UST_SESS I ON I D 

TOKEN_ALL_ACCESS 



Can be assigned as primary token 
Can be duplicated 

Can be assigned as impersonation token 

Can be queried 

Can be queried for source 

Token privileges can be adjusted 

Token groups can be adjusted 

Token default ACL and owner can be adjusted 

Token session id can be adjusted 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



TokenHandle 

Points to a variable that will receive the token object handle if the call is successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

OpenProcessToken. 

Remarks 

OpenProcessToken exposes the full functionality of ZwOpenProcessToken. 
TOKEN_ADJUST_SESSIONID is only valid in Windows 2000. 



ZwOpenThreadToken 



ZwOpenThreadToken opens the token of a thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenThreadToken ( 

IN HANDLE ThreadHandle, 

IN ACCESS_MASK DesiredAccess, 

IN BOOLEAN OpenAsSelf, 

OUT PHANDLE TokenHandle 

); 



Parameters 

ThreadHandle 

A handle to a thread. The handle must grant THREAD_QUERY_INFORMATION access. 
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DesiredAccess 

Specifies the type of access that the caller requires to the token object. This parameter 
can be zero, or any combination of the following flags: 



TOKEN_ASSIGN_PRIMARY 

TOKEN_DUPLICATE 

T0KEN_IMPERS0NATE 

TOKEN_QUERY 

TOKEN_QUERY_SOURCE 

TOKEN_ADJUST_PRIVILEGES 

T0KEN_ADJ UST_GR0UPS 

TOKEN_ADJUST_DEFAULT 

T0KEN_ADJ UST_SESS I ON I D 

TOKEN_ALL_ACCESS 



Can be assigned as primary token 
Can be duplicated 

Can be assigned as impersonation token 

Can be queried 

Can be queried for source 

Token privileges can be adjusted 

Token groups can be adjusted 

Token default ACL and owner can be adjusted 

Token session id can be adjusted 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Open As Self 

A boolean specifying whether the security context of the process should be used to 
check the access to the token object. If OpenAsSelf is false, the security context of the 
thread is used, which may be an impersonation context. 

TokenHandle 

Points to a variable that will receive the token object handle if the call is successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED , 
STATUS_INVALID_HANDLE, or STATUS_N0_T0KEN. 

Related Win32 Functions 

OpenThreadToken. 

Remarks 

OpenThreadToken exposes the full functionality of ZwOpenThreadToken. 
TOKEN_ADJUST_SESSIONID is only valid in Windows 2000. 



Z wD uplic ateToken 



ZwDuplieateToken makes a duplicate copy of a token. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDuplieateToken ( 

IN HANDLE ExistingTokenHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 

IN BOOLEAN Eff ectiveOnly , 

IN T0KEN_TYPE TokenType, 

OUT PHANDLE NewTokenHandle 

); 
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Parameters 

ExistingTokenHandle 

A handle to a token object. The handle must grant TOKEN_DUPLICATE access. 



DesiredAccess 

Specifies the type of access that the caller requires to the token object. This parameter 
can be zero, or any combination of the following flags: 



TOKEN_ASSIGN_PRIMARY 

TOKEN_DUPLICATE 

T0KEN_IMPERS0NATE 

TOKEN_QUERY 

TOKEN_QUERY_SOURCE 

TOKEN_ADJUST_PRIVILEGES 

T0KEN_ADJ UST_GR0UPS 

TOKEN_ADJUST_DEFAULT 

TOKEN_ADJUST_SESSIONID 

TOKEN_ALL_ACCESS 



Can be assigned as primary token 
Can be duplicated 

Can be assigned as impersonation token 

Can be queried 

Can be queried for source 

Token privileges can be adjusted 

Token groups can be adjusted 

Token default ACL and owner can be adjusted 

Token session id can be adjusted 

All of the preceding + 

STANDARD_RIGHTS_REQUIRED 



Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a token object. 

Effective Only 

A boolean specifying whether the privileges and groups present, but disabled, in the 
existing token may be enabled in the new token. 

TokenType 

Specifies the type of token object to be created. The permitted values are drawn from 
the enumeration TOKEN_TYPE: 

typedef enum _TOKEN_TYPE { 

TokenPrimary = 1 , 

Token Impersonation 
} TOKEN_TYPE, *PTOKEN_TYPE; 

NewTokenHandle 

Points to a variable that will receive the token object handle if the call is successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

DuplicateToken, DuplicateTokenEx. 

Remarks 

DuplicateTokenEx exposes most of the functionality of ZwDuplicateToken. 
TOKEN_ADJUST_SESSIONID is only valid in Windows 2000. 
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ZwFilterToken 



ZwFilterToken creates a child of an existing token and applies restrictions to the child 
token. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFilterToken( 

IN HANDLE ExistingTokenHandle, 

IN ULONG Flags, 

IN PT0KEN_GR0UPS SidsToDisable , 

IN PT0KEN_PRl VI LEGES PrivilegesToDelete , 

IN PT0KEN_GR0UPS SidsToRestricted , 

OUT PHANDLE NewTokenHandle 

); 



Parameters 



ExistingTokenHandle 

A handle to a token object. The handle must grant TOKEN_DUPLICATE access. 

Flags 

A bit array of flags that affect the filtering of the token. The following value is defined: 

DELETE_MAX_PRIVILEGES 1 // Delete all privileges except 

// SeChangeNotifyPrivilege 



SidsToDisable 

Points to a structure that specifies which SIDs are to be disabled in the new token 
(by adding the attribute SE_GROUP_USE_FOR_DENY_ONLY to the SID). SIDs present in 
SidsToDisable that are not present in the existing token are ignored, as are the 
Attributes members of the array SidsToDisable->Groups. 

Privileges ToDelete 

Points to a structure that specifies which privileges present in the existing token are 
not to be copied to the new token. Privileges present in PrivilegesToDelete that are 
not present in the existing token are ignored, as are the Attributes members of the 
array PrivilegesToDelete ^Privileges. If Flags specifies DELETE_MAX_PRIVILEGES 
and SeChangeNotifyPrivilege is present in PrivilegesToDelete, it is deleted along 
with all other privileges. 

SidsToRestrict 

Points to a structure that specifies which SIDs are to be added to the restricted SIDs 
of the token. SIDs present in SidsToRestrict that are already present in the 
restricted SIDs of the existing token are ignored. The Attributes members of 
SidsToRestrict ->Groups must be zero. 

NewTokenHandle 

Points to a variable that will receive the token object handle if the call is successful. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

CreateRestrictedToken. 

Remarks 

CreateRestrictedToken exposes the full functionality of ZwFilterToken. 

The routine ZwFilterToken is only present in Windows 2000. 



ZwAdjustPrivilegesToken 



ZwAdjustPrivilegesToken adjusts the attributes of the privileges in a token. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAdjustPrivilegesToken( 

IN HANDLE TokenHandle, 

IN BOOLEAN DisableAllPrivileges, 

IN PT0KEN_PRI VI LEGES NewState, 

IN ULONG BufferLength, 

OUT PT0KEN_PRI VI LEGES PreviousState OPTIONAL, 

OUT PULONG ReturnLength 

); 



Parameters 

TokenHandle 

A handle to a token object. The handle must grant TOKEN_ADJUST_PRIVILEGES access. 
DisableAllPrivileges 

A boolean specifying whether all of the token’s privileges should be disabled. If 
DisableAllPrivileges is true, the NewState parameter is ignored. 

NewState 

Points to a structure that specifies the new state of a set of privileges present in the 
token. 

BufferLength 

Specifies the size in bytes of the structure pointed to by PreviousState. 

PreviousState 

Points to a caller-allocated buffer or variable that receives the previous state of the 
privileges. If PreviousState is not a null pointer, TokenHandle must also grant 
TOKEN QUERY access. 
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RetumLength 

Optionally points to a variable that receives the number of bytes actually returned to 
PreviousState if the call was successful. If PreviousState is not a null pointer, 
RetumLength must be a valid pointer. 

Return Value 

Returns STATUS_SUCCESS, STATUS_NOT_ALL_ASSIGNED or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_I N VAL I D_HANDLE, or STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

Ad j ustToken Privileges. 

Remarks 

Ad j ustTokenPrivileges exposes the full functionality of ZwAdjustTokenPrivileges. 



ZwAdjustGroupsToken 



ZwAdjustGroupsToken adjusts the attributes of the groups in a token. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAdjustGroupsToken( 

IN HANDLE TokenHandle, 

IN boolean ResetToDef ault , 

IN PT0KEN_GR0UPS NewState, 

IN ULONG BufferLength, 

OUT PT0KEN_GR0UPS PreviousState OPTIONAL, 

OUT PULONG RetumLength 

); 



Parameters 

TokenHandle 

A handle to a token object. The handle must grant TOKEN_ADJUST_GROUPS access. 

ResetToDefault 

A boolean specifying whether all of the token’s groups should be reset to their default 
state. If ResetToDefault is true, the NewState parameter is ignored. 

NewState 

Points to a structure that specifies the new state of a set of groups present in the token. 

BufferLength 

Specifies the size in bytes of the structure pointed to by PreviousState. 

PreviousState 

Points to a caller-allocated buffer or variable that receives the previous state of the 
groups. If PreviousState is not a null pointer, TokenHandle must also grant 
TOKEN QUERY access. 
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ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
PreviousState if the call was successful. If PreviousState is not a null pointer, 
ReturnLength must be a valid pointer. 

Return Value 

Returns STATUS_SUCCESS, STATUS_NOT_ALL_ASSIGNED or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_I N VAL I D_HANDLE, or STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

Ad j ustTokenGroups. 

Remarks 

Ad j ustTokenGroups exposes the full functionality of ZwAdj ustTokenGroups. 



ZwQuerylnformationToken 



ZwQuerylnformationToken retrieves information about a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationToken ( 

IN HANDLE TokenHandle , 

IN T0KEN_INF0RMATI0N_CLASS Tokenlnf ormationClass , 

OUT PVOID Tokenlnformation, 

IN ULONG TokenlnformationLength, 

OUT PULONG ReturnLength 

); 



Parameters 

TokenHandle 

A handle to a token object. The handle must grant TOKEN_QUERY access for most infor- 
mation classes. To query the token source TOKEN_QUERY_SOURCE access must be granted. 

TokenlnformationClass 

Specifies the type of token information to be queried. The permitted values are drawn 
from the enumeration TOKEN_INFORMATION_CLASS, described in the following section. 

Tokenlnform ation 

Points to a caller-allocated buffer or variable that receives the requested token 
information. 

TokenlnformationLength 

Specifies the size in bytes of Tokenlnformation, which the caller should set according 
to the given TokenlnformationClass. 
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ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
Tokenlnformation; if Tokenlnf ormationLength is too small to contain the available 
data, ReturnLength points to the number of bytes required for the available data. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

GetToken Inf ormation. 

Remarks 

GetTokenlnf ormation exposes the full functionality of ZwQuerylnformationToken. 



ZwSetlnformationToken 



ZwSetlnformationToken sets information affecting a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationToken ( 

IN HANDLE TokenHandle, 

IN T0KEN_INF0RMATI0N_CLASS TokenlnformationClass, 

IN PVOID Tokenlnformation, 

IN ULONG TokenlnformationLength 

); 



Parameters 

TokenHandle 

A handle to a token object. The handle must grant TOKEN_ADJUST_DEFAULT access. 
Some information classes also require TOKEN_ADJUST_SESSIONID access. 

TokenlnformationClass 

Specifies the type of token information to be set. The permitted values are a subset of 
the enumeration TOKEN_INFORMATION_CLASS, described in the following section. 

Tokenlnform at ion 

Points to a caller-allocated buffer or variable that contains the token information to 
be set. 

TokenlnformationLength 

Specifies the size in bytes of Tokenlnformation, which the caller should set according 
to the given TokenlnformationClass. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_I NVALI D_HANDLE, STATUS_I NVAL I D_I NF0_CLASS, 
STATUS_INFO_LENGTH_MISMATCH, STATUS_INVALID_0WNER, or 
STATUS_ALLOTTED_SPACE_EXCEEDED. 

Related Win32 Functions 

SetTokenlnf ormation. 

Remarks 

SetTokenlnf ormation exposes the full functionality of ZwSetlnformationToken. 



TOKEN_INFORMATION_CLASS 



Query Set 

typedef enum _T0KEN_INF0RMATI0N_CLASS { 



TokenUser = 1 , 


// 


1 


Y 


N 


TokenGroups, 


a 


2 


Y 


N 


TokenPrivileges, 


a 


3 


Y 


N 


TokenOwner, 


a 


4 


Y 


Y 


TokenPrimaryGroup, 


a 


5 


Y 


Y 


TokenDefaultDacl, 


a 


6 


Y 


Y 


TokenSource, 


a 


7 


Y 


N 


TokenType, 


a 


8 


Y 


N 


TokenlmpersonationLevel, 


a 


9 


Y 


N 


TokenStatistics, 


a 


10 


Y 


N 


TokenRestrictedSids, 


a 


11 


Y 


N 


TokenSessionld 


a 


12 


Y 


Y 



} T0KEN_INF0RMATI0N_CLASS; 



TokenUser 



typedef struct _T0KEN_USER { // Information Class 1 
SID_AND_ATTRIBUTES User; 

} T0KEN_USER, *PT0KEN_USER ; 

Members 

User 

The SID of the user. No attributes are defined. 



Remarks 

None. 



TokenGroups and TokenRestrictedSids 



typedef struct _T0KEN_GR0UPS { // Information Classes 2 and 11 
UL0NG GroupCount; 

SID_AND_ATTRIBUTES Groups [ANYSIZE_ARRAY] ; 

} T0KEN_GR0UPS, *PT0KEN_GR0UPS; 
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Members 



GroupCount 

The numbers of groups in the array Groups 



Groups 

An array of SIDs of groups and their associated attributes. The following attributes are 
defined: 



SE_GR0UP_MANDAT0RY 

SE_GROUP_ENABLED_BY_DEFAULT 

SE_GROUP_ENABLED 

SE_GR0UP_0WNER 

SE_GR0UP_USE_F0R_DENY_0NLY 

SE_GR0UP_RES0URCE 

SE_GR0UP_L0G0N_ID 



0x00000001 

0x00000002 

0x00000004 

0x00000008 

0x00000010 

0x20000000 

0XC0000000 



Remarks 

TokenRestr'ictedSids is only valid in Windows 2000. 



TokenPrivileges 



typedef struct _T0KEN_PRIVILEGES { // Information Class 3 
UL0NG PrivilegeCount ; 

LUID_AND_ATTRIBUTES Privileges [ANYSIZE_ARRAY] ; 

} T0KEN_PRIVILEGES , *PT0KEN_PRIVILEGES; 



Members 

PrivilegeCount 

The numbers of privileges in the array Privileges. 



Privileges 

An array of LUIDs identifying privileges and their associated attributes. The following 
attributes are defined: 

SE_PRIVILEGE_ENABLED_BY_DEFAULT 0x00000001 
SE_PRIVILEGE_ENABLED 0x00000002 

Remarks 

None. 



TokenOwner 



typedef struct _T0KEN_0WNER { // Information Class 4 
PSID Owner; 

} T0KEN_0WNER, *PT0KEN_0WNER ; 
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Members 

Owner 

The SID that will be recorded as the owner of any objects created by a process using 
this access token. 

Remarks 

None. 



Toke nPr im ar y Gro up 



typedef struct _T0KEN_PRIMARY_GR0UP { // Information Class 5 
PSID PrimaryGroup; 

} T0KEN_PRIMARY_GR0UP , *PT0KEN_PRIMARY_GR0UP; 

Members 

PrimaryGroup 

The SID that will be recorded as the primary group of any objects created by a 
process using this access token. 

Remarks 

None. 



TokenDefaultDacl 



typedef struct _TOKEN_DEFAULT_DACL { // Information Class 6 
PACL DefaultDacl; 

} TOKEN_DEFAULT_DACL , *PTOKEN_DEFAULT_DACL; 

Members 

DefaultDacl 

The Discretionary ACL that will be assigned to any objects created by a process using 
this access token, unless an explicit ACL is specified. 

Remarks 

None. 



TokenSource 



typedef struct _T0KEN_S0URCE { // Information Class 7 
CHAR SourceName[8] ; 

LUID Sourceldentif ier; 

} T0KEN_S0URCE , *PT0KEN_S0URCE; 
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Members 

SourceName 

A textual identifier of the creator of the token. 

Sourceldentijier 

A numeric identifier of the creator of the token. 

Remarks 

None. 



TokenType 



typedef enum _T0KEN_TYPE { // Information Class 8 
TokenPrimary = 1 , 

Tokenlmpersonation 
} T0KEN_TYPE, *PT0KEN_TYPE; 



TokenlmpersonationLevel 



typedef enum _SECURITY_IMPERSONATION_LEVEL { // Information Class 9 
SecurityAnonymous , 

Security Identif ication, 

Security Impersonation, 

SecurityDelegation 

} SECURITY_IMPERSONATION_LEVEL , * PSECURITY_IMPERSONATION_LEVEL ; 



TokenStatistics 



typedef struct _TOKEN_STATISTICS { // Information Class 10 
LUID Tokenld; 

LUID Authenticationld; 

LARGE_INTEGER ExpirationTime ; 

T0KEN_TYPE TokenType; 

SECURITY_IMPERSONATION_LEVEL ImpersonationLevel ; 

ULONG DynamicCharged; 

ULONG DynamicAvailable; 

ULONG GroupCount; 

ULONG PrivilegeCount ; 

LUID Modifiedld; 

} TOKEN_STATISTICS , *PTOKEN_STATISTICS; 

Members 

Tokenld 

A locally unique identifier (LUID) that identifies the instance of the token object. 

Authenticationld 

A LUID assigned to the session the token represents. There can be many tokens repre- 
senting a single logon session. 
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Expiration Time 

The time at which the token expires in the standard time format (that is, the number 
of 100-nanosecond intervals since January 1, 1601). An expiration time value of— 1 
indicates that the token does not expire. 

TokenType 

Specifies the type of the token (primary or impersonation). 

ImpersonationLevel 

Specifies the impersonation level of the token. This member is valid only if the 
TokenType is Tokenlmpersonation. 

DynamicCharged 

The size, in bytes, of memory allocated for storing default protection and a primary 
group identifier. 

DynamicAvailable 

The size, in bytes, of memory allocated for storing default protection and a primary 
group identifier that has not been used. 

Group Count 

The number of group SIDs included in the token. 

Privilege Count 

The number of privileges included in the token. 

Modifiedld 

A LUID that changes each time the token is modified. An application can use this 
value as a test of whether a security context has changed since it was last used. 

Remarks 

None. 



TokenSessionld 



ULONG Sessionld; // Information Class 12 
A numeric identifier for a session. 

TokenSessionld is only valid in Windows 2000. 

Although the session identifier can be set in any version ofWindows 2000, it is only 
meaningful to Windows Terminal Server. 
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Example 8.1: Creating a command window for the 
SYSTEM user 



#include "ntdll.h" 

PVOID GetFromToken (HANDLE hToken, T0KEN_INF0RMATI0N_CLASS tic) 

{ 

DWORD n; 

BOOL rv = GetTokenInformation(hToken, tic, 0, 0, &n); 

if (rv == FALSE && GetLastError ( ) != ERROR_INSUFFICIENT_BUFFER) return 0; 
PBYTE p = new BYTE [ n ] ; 

return GetTokenlnformation (hToken, tic, p, n, &n) == FALSE ? 0 : p; 

} 

HANDLE SystemToken( ) 

{ 

EnablePrivilege ( SE_CREATE_TOKEN_NAME ) ; 

HANDLE hToken; 

OpenProcessToken(GetCurrentProcess( ) , T0KEN_QUERY | T0KEN_QUERY_S0URCE , 
&hToken) ; 

SID_IDENTIFIER_AUTHORITY nt = SECURITY_NT_AUTHORITY ; 

PSID system; 

AllocateAndlnitializeSid (&nt , 1, SECUR ITY_LOCAL_SYSTEM_R I D , 

0, 0, 0, 0, 0, 0, 0, &system); 

TOKENJJSER user = {{system, 0}}; 

LUID luid; 

AllocateLocallyUniqueId(&luid) ; 

T0KEN_S0URCE source ={{'*' , '*', 'A', ' N 1 , 'O', ' N ' , 

{luid. LowPart , luid.HighPart}}; 

LUID authid = SYSTEM_LUID; 

PTOKEN_STATISTICS Stats 

= PTOKEN_STATISTICS(GetFromToken(hToken, TokenStatistics) ) ; 

NT: : SECUR ITY_QUALITY_OF_SERVICE sqos 

= {sizeof sqos, NT: :SecurityAnonymous, 

SECUR ITY_STATIC_TRACKING, FALSE} ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa, 0, 0, 0, 0, &sqos}; 

HANDLE hToken2 = 0; 

NT: :ZwCreateToken(&hToken2, TOKEN_ALL_ACCESS, &oa, TokenPrimary , 

NT: :PLUID(&authid) , // NT : : PLUID (&st at s - Authentication Id) , 

NT : :PLARGE_INTEGER(&stats->ExpirationTime) , 

&user, 

PTOKEN_GROUPS(GetFromToken(hToken, TokenGroups) ) , 
PTOKEN_PRIVILEGES(GetFromToken(hToken, TokenPrivileges) ) , 
PT0KEN_0WNER (GetFromToken (hToken, TokenOwner) ) , 
PTOKEN_PRIMARY_GROUP (GetFromToken (hToken, TokenPrimaryGroup) ) , 
PTOKEN_DEFAULT_DACL (GetFromToken (hToken, TokenDef aultDacl) ) , 
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&source) ; 

CloseHandle(hToken) ; 
return hToken2; 

} 

int main() 

{ 

PR0CESS_INF0RMATI0N pi; 

STARTUPINFO si = {sizeof si}; 

return CreateProcessAsUser(SystemToken( ) , 0, "cmd", 0, 0, FALSE, 

C R EAT E_N EW_C0N SO L E j CREATE_NEW_PR0CESS_GR0UP , 

0, 0 , &si, &pi); 

} 

Here error handling is not so great again. 

For example, in the function HANDLE SystemToken( ) you have 
BOOL rv = EnablePrivilege ( SE_CREATE_TOKEN_NAME ) ; 

However, rv is never used! 

Example 8.1 copies most of the information for the new token from the existing 
token, but changes the token user to be SYSTEM and changes the authentication 
identifier to be SYSTEM_LUID, breaking the link between the new token and the cre- 
dentials of the current user. 

If NT : : PLUID(&stats ->AuthenticationId) had been used as the authentication iden- 
tifier rather than NT : : PLUID(&authid) , the token would represent SYSTEM on the 
local system and the logged on user on the network. 
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Synchronization 



The system services described in this chapter create and manipulate objects that can 
be used to synchronize threads. 






ZwWaitForSingleObject waits for an object to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWaitForSingleObject ( 

IN HANDLE Handle, 

IN boolean Alertable, 

IN PLARGE_INTEGER Timeout OPTIONAL 
); 

Parameters 

Handle 

A handle to an object. The handle must grant SYNCHRONIZE access. 

Alertable 

A boolean specifying whether the wait can be interrupted by the delivery of a user 



Timeout 

Optionally points to a value that specifies the absolute or relative time at which the 



time. The value is expressed in units of 100 nanoseconds. Absolute times track any 
changes in the system time; relative times are not affected by system time changes. If 
Timeout is a null pointer, the wait will not timeout. 

Return Value 

Returns STATUS_SUCCESS, STATUS_ALERTED, STATUS_USER_APC, STATUS_TIMEOUT, 
STATUS_ABANDONED, or an error status, such as STATUS_ACCESS_DENIED or 




APC. 



wait is to be timed out. A negative value specifies an interval relative to the current 



STATUS INVALID HANDLE. 
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Related Win32 Functions 

WaitForSingleOb j ect, WaitForSingleOb j ectEx. 

Remarks 

WaitForSingleOb] ectEx exposes most of the functionality of ZwWaitForSingleObj ect. 

The Handle parameter can be a handle to any kernel object type. If the object is not 
waitable, it is considered to be always signaled. 



ZwSignalAndWaitForSingleObject 



ZwSignalAndWaitForSingleObject signals one object and waits for another to become 
signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSignalAndWaitForSingleObject ( 

IN HANDLE HandleToSignal, 

IN HANDLE HandleToWait , 

IN BOOLEAN Alertable, 

IN PLARGE_INTEGER Timeout OPTIONAL 

); 

Parameters 

HandleToSignal 

A handle to the object that is to be signaled. This object can be a semaphore, a mutant, 
or an event. If the handle is a semaphore, SEMAPHORE_MODIFY_STATE access is required. If 
the handle is an event, EVENT_MODIFY_STATE access is required. If the handle is a mutant, 
SYNCHRONIZE access is assumed because only the owner of a mutant may release it. 

HandleToWait 

A handle to the object that is to be waited upon. The handle must grant SYNCHRONIZE 
access. 

Alertable 

A boolean specifying whether the wait can be interrupted by the delivery of a 
user APC. 

Timeout 

Optionally points to a value that specifies the absolute or relative time at which the 
wait is to be timed out. A negative value specifies an interval relative to the current 
time. The value is expressed in units of 100 nanoseconds. Absolute times track any 
changes in the system time; relative times are not affected by system time changes. If 
Timeout is a null pointer, the wait will not timeout. 
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Return Value 

Returns STATUS_SUCCESS, STATUS_ALERTED, STATUS_USER_APC, STATUS_TIMEOUT, 

ST ATUS_ABANDON ED, or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

SignalOb j ectAndWait. 

Remarks 

SignalOb j ectAndWait exposes most of the functionality of 
ZwSignalAndWaitForSingleOb j ect. 

The HandleToWait parameter can be a handle to any kernel object type. If the object is 
not waitable, it is considered to be always signaled. 



ZwWaitForMultipleObjects 



ZwWaitForMultipleObjects waits for one or more objects to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWaitForMultipleObjects( 

IN ULONG HandleCount , 

IN PHANDLE Handles, 

IN WAIT_TYPE WaitType, 

IN BOOLEAN Alertable, 

IN PLARGE_INTEGER Timeout OPTIONAL 

); 



Parameters 

HandleCount 

The number of handles to objects to be waited on. This value must be at most 

MAXIMUM_WAIT_OBJECTS. 

Handles 

Points to a caller- allocated buffer or variable that contains the array of object handles 
to be waited upon. Each handle must grant SYNCHRONIZE access. 

WaitType 

Specifies the type of wait to be performed. The permitted values are drawn from the 
enumeration WAIT_TYPE: 

typedef enum _WAIT_TYPE { 

WaitAll, // Wait for any handle to be signaled 

WaitAny // Wait for all handles to be signaled 

} WAIT_TYPE, *PWAIT_TYPE; 



Alertable 



A boolean specifying whether the wait can be interrupted by the delivery of a 
user APC. 
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Timeout 

Optionally points to a value that specifies the absolute or relative time at which the 
wait is to be timed out. A negative value specifies an interval relative to the current 
time. The value is expressed in units of 100 nanoseconds. Absolute times track any 
changes in the system time; relative times are not affected by system time changes. If 
Timeout is a null pointer, the wait will not timeout. 

Return Value 

Returns STATUS_SUCCESS, STATUS_ALERTED, STATUS_USER_APC, STATUS_TIMEOUT, 
STATUS_ABANDONED, STATUS_ABANDONED_WAIT_0 to STATUS_ABAND0NED_WAIT_63, 
STATUS_WAIT_0 to STATUS_WAIT_63, or an error status, such as STATUS_ACCESS__DENIE0 or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

WaitForMultipleOb j ects, WaitForMultipleOb j ectsEx. 

Remarks 

WaitForMultipleOb] ectsEx exposes most of the functionality of 
ZwWaitForMultipleObjeets. 

The handles in the Handles parameter can be handles to any kernel object type. If the 
object is not waitable, it is considered to be always signaled. 



ZwCreateTimer 



ZwCreateTimer creates or opens a timer object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateTimer ( 

OUT PHANDLE TimerHandle, 

IN ACCESS_MASK DesiredAccess , 

IN P0BJECT_ATTRIBUTES 0b j ectAttributes , 

IN TIMER_TYPE TimerType 

); 



Parameters 

TimerHandle 

Points to a variable that will receive the timer object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the timer object. This parameter 
can be zero, or any combination of the following flags: 

TIMER_QUERY_STATE Query access 

TIMER_M0DIFY_STATE Modify access 

TIMER_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 
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Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a timer object. 

TimerType 

Specifies the type of the timer. The permitted values are drawn from the enumeration 
TIMER_TYPE: 

typedef enum _TIMER_TYPE { 

Notif icationTimer, // A manual-reset timer 

SynchronizationTimer // An auto-reset timer 

} TIMER_TYPE; 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 



Related Win32 Functions 

CreateWaitableTimer. 



Remarks 

CreateWaitableTimer exposes most of the functionality of ZwCreateTimer. 



ZwOpenTimer 



ZwOpenTimer opens a timer object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenTimer( 

OUT PHANDLE TimerHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes 

); 



Parameters 

TimerHandle 

Points to a variable that will receive the timer object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the timer object. This parameter 
can be zero, or any combination of the following flags: 

TIMER_QUERY_STATE Query access 

TIMER_MODIFY_STATE Modify access 

TIMER_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Obj ectAttributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a timer object. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJECT_NAME_NOT_FOUND. 

Related Win32 Functions 

OpenWaitableTimer. 

Remarks 

OpenWaitableTimer exposes most of the functionality of ZwOpenTimer. 



ZwCancelTimer 



ZwCancelTimer deactivates a timer. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCancelTimer ( 

IN HANDLE TimerHandle, 

OUT PB00LEAN PreviousState OPTIONAL 

); 



Parameters 

TimerHandle 

A handle to a timer object. The handle must grant TIMER_MODIFY_STATE access. 

PreviousState 

Optionally points to a variable that receives the signal state of the timer. A value of 
true means that the timer is signaled. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

CancelWaitableTimer. 

Remarks 

CancelWaitableTimer exposes most of the functionality of ZwCancelTimer. 

If the timer is not signaled when ZwCancelTimer is invoked, any waiting threads contin- 
ue to wait until either they timeout the wait, or the timer is reactivated (by 
ZwSetTimer) and eventually signaled. 
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ZwSetTimer 



ZwSetTimer sets properties of and activates a timer. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetTimer ( 

IN HANDLE TimerHandle, 

IN PLARGE_INTEGER DueTime, 

IN PTIMER_APC_ROUTINE TimerApcRoutine OPTIONAL, 
IN PVOID TimerContext , 

IN BOOLEAN Resume, 

IN LONG Period, 

OUT PB00LEAN PreviousState OPTIONAL 

); 



Parameters 

TimerHandle 

A handle to a timer object. The handle must grant TIMER_MODIFY_STATE access. 

DueTime 

Points to a value that specifies the absolute or relative time at which the timer is to be 
signaled. A negative value specifies an interval relative to the current time. The value is 
expressed in units of 100 nanoseconds. Absolute times track any changes in the system 
time; relative times are not affected by system time changes. 

TimerApcRoutine 

Specifies an optional timer APC routine. The timer APC routine has the following 
prototype: 

VOID (APIENTRY *PTIMER_APC_ROUTINE) (PVOID TimerContext, 

ULONG TimerLowValue, 

ULONG TimerHighValue) ; 



TimerContext 

A void pointer that will be passed as argument to the timer APC routine. 

Resume 

Specifies whether to restore a system in suspended power conservation mode when 
the timer state is set to signaled. 

Period 

The period of the timer, in milliseconds. If Period is zero, the timer is signaled once. If 
Period is greater than zero, the timer is periodic. 

PreviousState 

Optionally points to a variable that receives the signal state of the timer. A value of 
true means that the timer is signaled. 
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Return Value 

Returns STATUS_SUCCESS, STATUS_TIMER_RESUME_IGNORED or an error status, such as 
STATUS_ACCESS_DENIED or STATUS_INVALID_HANDLE. 

Related Win32 Functions 

SetWaitableTimer. 

Remarks 

SetWaitableTimer exposes most of the functionality of ZwSetTimer. 



ZwQueryTimer 



ZwQueryTimer retrieves information about a timer object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryTimer( 

IN HANDLE TimerHandle, 

IN TIMER_INFORMATION_CLASS Timerlnf ormationClass , 

OUT PVOID Timerlnformation, 

IN ULONG TimerlnformationLength, 

OUT PULONG ResultLength OPTIONAL 

); 

Parameters 

TimerHandle 

A handle to a timer object. The handle must grant TIMER_QUERY_STATE access. 

TimerlnformationClass 

Specifies the type of timer object information to be queried. The permitted values 
are drawn from the enumeration TIMER_INFORMATION_CLASS, described in the following 
section. 

Timerlnformation 

Points to a caller- allocated buffer or variable that receives the requested timer object 
information. 

TimerlnformationLength 

The size in bytes of Timerlnformation, which the caller should set according to the 
given Timerlnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Timerlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 



TIMER_INFORMATION_CLASS 



typedef enum _TIMER_INFORMATION_CLASS { 
TimerBasicInformation 
} TIMER_INFORMATION_CLASS; 



TimerBasicInformation 



typedef struct _TIMER_BASIC_INFORMATION { 

LARGE_INTEGER TimeRemaining; 

BOOLEAN SignalState; 

} TIMER_BASIC_INFORMATION , *PTIMER_BASIC_INFORMATION ; 

Members 

TimeRemaining 

The number of 100-nanosecond units remaining before the timer is next signaled. 



SignalState 

A boolean indicating whether the timer is signaled. 

Remarks 

None. 



ZwCreateEvent 



ZwCreateEvent creates or opens an event object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateEvent ( 

OUT PHANDLE EventHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 

IN EVENT_TYPE EventType, 

IN BOOLEAN initialState 

); 
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Parameters 

EventHandle 

Points to a variable that will receive the event object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the event object. This parameter 
can be zero, or any combination of the following flags: 

EVENT_QUERY_STATE Query access 

EVENT_MODIFY_STATE Modify access 

EVENT_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for an event object. 

EventType 

Specifies the type of the event. The permitted values are drawn from the enumeration 
EVENT_TYPE: 

typedef enum _EVENT_TYPE { 

Notif icationEvent , // A manual-reset event 

SynchronizationEvent // An auto-reset event 

} EVENT_TYPE; 



InitialState 

Specifies the initial state of the event. TRUE indicates signaled. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

CreateEvent. 



Remarks 

CreateEvent exposes most of the functionality of ZwCreateEvent. 



ZwOpenEvent 



ZwOpenEvent opens an event object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenEvent( 

OUT PHANDLE EventHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 
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Parameters 

EventHandle 

Points to a variable that will receive the event object handle if the call is successful. 
DesiredAccess 

Specifies the type of access that the caller requires to the event object. This parameter 
can be zero, or any combination of the following flags: 

EVENT_QUERY_STATE Query access 

EVENT_MODIFY_STATE Modify access 

EVENT_ALL_ACCESS All of the preceding + ST AN DARD_R I GHTS_AL L 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for an event object. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

OpenEvent. 



Remarks 

OpenEvent exposes most of the functionality of ZwOpenEvent. 



ZwSetEvent 



ZwSetEvent sets an event object to the signaled state. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetEvent ( 

IN HANDLE EventHandle, 

OUT PULONG PreviousState OPTIONAL 

); 



Parameters 

EventHandle 

A handle to an event object. The handle must grant EVENT_MODIFY_STATE access. 
PreviousState 

Optionally points to a variable that receives the previous signal state of the event. A 
non-zero value means that the event was signaled. 





CH09 11.24.99 09:55 Page 218 



218 Synchronization: ZwSetEvent 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

SetEvent. 

Remarks 

SetEvent exposes most of the functionality of ZwSetEvent. 



ZwPulseEvent 



ZwPulseEvent sets an event object to the signaled state releasing all or one waiting 
thread (depending upon the event type) and then resets the event to the unsignaled 
state. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPulseEvent ( 

IN HANDLE EventHandle, 

OUT PULONG PreviousState OPTIONAL 

); 



Parameters 

EventHandle 

A handle to an event object. The handle must grant EVENT_MODIFY_STATE access. 

PreviousState 

Optionally points to a variable that receives the previous signal state of the event. A 
non-zero value means that the event was signaled. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

PulseEvent. 

Remarks 

PulseEvent exposes most of the functionality of ZwPulseEvent. 
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ZwResetEvent 



ZwResetEvent resets an event object to the unsignaled state. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwResetEvent ( 

IN HANDLE EventHandle, 

OUT PULONG PreviousState OPTIONAL 

); 



Parameters 

EventHandle 

A handle to an event object. The handle must grant EVENT_MODIFY_STATE access. 

PreviousState 

Optionally points to a variable that receives the previous signal state of the event. A 
non-zero value means that the event was signaled. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The Win32 function ResetEvent uses the native function ZwClearEvent, which differs 
from ZwResetEvent by not returning the previous state of the event. 



ZwClearEvent 



ZwClearEvent resets an event object to the unsignaled state. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwClearEvent ( 

IN HANDLE EventHandle 

); 



Parameters 

EventHandle 

A handle to an event object. The handle must grant EVENT_MODIFY_STATE access. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS INVALID HANDLE. 
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Related Win32 Functions 

ResetEvent. 



Remarks 

ResetEvent exposes the full functionality of ZwClearEvent. 



ZwQueryEvent 



ZwQueryEvent retrieves information about an event object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryEvent ( 

IN HANDLE EventHandle , 

IN EVENT_INF0RMATI0N_CLASS Event Inf ormationClass , 

OUT PVOID Eventlnformation, 

IN ULONG EventlnformationLength, 

OUT PULONG ResultLength OPTIONAL 

); 

Parameters 

EventHandle 

A handle to an event object. The handle must grant EVENT_QUERY_STATE access. 

EventlnformationClass 

Specifies the type of event object information to be queried. The permitted values 
are drawn from the enumeration EVENT_INFORMATION_CLASS, described in the following 
section. 

Eventlnformation 

Points to a caller- allocated buffer or variable that receives the requested event object 
information. 

EventlnformationLength 

The size in bytes of Eventlnformation, which the caller should set according to the 
given EventlnformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Eventlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 





1996 CH09 11.24.99 09:55 Page 221 



Synchronization: ZwCreateSemaphore 



221 



Related Win32 Functions 

None. 



Remarks 

None. 



EVENT_INFORMATION_CLASS 



typedef enum _EVENT_INFORMATION_CLASS { 
EventBasicInformation 
} EVENT_INFORMATION_CLASS ; 



EventBasicInformation 



typedef struct _EVENT_BASIC_INFORMATION { 

EVENT_TYPE EventType; 

LONG SignalState; 

} EVENT_BASIC_INFORMATION , *PEVENT_BASIC_INFORMATION ; 

Members 

EventType 

The type of the event. The permitted values are drawn from the enumeration 
EVENT_TYPE: 

typedef enum _EVENT_TYPE { 

NotificationEvent , //A manual- reset event 

SynchronizationEvent // An auto-reset event 

} EVENT_TYPE; 



SignalState 

Indicates whether the event is signaled. A non-zero value means that the event is 
signalled. 



Remarks 

None. 



ZwCreateSemaphore 



ZwCreateSemaphore creates or opens a semaphore object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateSemaphore ( 

OUT PHANDLE SemaphoreHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES ObjectAttributes, 

IN LONG InitialCount , 

IN LONG MaximumCount 

); 
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Parameters 

SemaphoreHandle 

Points to a variable that will receive the semaphore object handle if the call is 
successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the semaphore object. This para- 
meter can be zero, or any combination of the following flags: 

SEMAPHORE_QUERY_STATE Query access 
SEMAPH0RE_M0DIFY_STATE Modify access 

SEMAPHORE_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a semaphore object. 

InitialCount 

Specifies the initial count for the semaphore object. 

Maximum Count 

Specifies the maximum count for the semaphore object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

CreateSemaphore. 

Remarks 

CreateSemaphore exposes most of the functionality of ZwCreateSemaphore. 



ZwOpenSemaphore 



ZwOpenSemaphore opens a semaphore object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenSemaphore ( 

OUT PHANDLE SemaphoreHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Ob j ectAttributes 

); 
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Parameters 

SemaphoreHandle 

Points to a variable that will receive the semaphore object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the semaphore object. This para- 
meter can be zero, or any combination of the following flags: 

SEMAPHORE_QUERY_STATE Query access 
SEMAPHORE_MODIFY_STATE Modify access 

SEMAPHORE_ALL_ACCESS All of the preceding + ST AN DARD_R I GHTS_AL L 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a semaphore object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

OpenSemaphore. 

Remarks 

OpenSemaphore exposes most of the functionality of ZwOpenSemaphore. 



ZwReleaseSemaphore 



ZwReleaseSemaphore increases the count of a semaphore by a given amount. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReleaseSemaphore ( 

IN HANDLE SemaphoreHandle, 

IN LONG ReleaseCount , 

OUT PLONG PreviousCount OPTIONAL 

); 



Parameters 

SemaphoreHandle 

A handle to a semaphore object. The handle must grant SEMAPHORE_MODIFY_STATE 
access. 

ReleaseCount 

Specifies the amount by which the semaphore object’s current count is to be 
increased. 





1996 CH09 11.24.99 09:55 Page 224 



224 Synchronization: ZwReleaseSemaphore 

PreviousCount 

Optionally points to a variable that receives the previous count for the semaphore. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

ReleaseSemaphore. 

Remarks 

ReleaseSemaphore exposes the full functionality of ZwReleaseSemaphore. 



ZwQuerySemaphore 



ZwQuerySemaphore retrieves information about a semaphore object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySemaphore ( 

IN HANDLE SemaphoreHandle, 

IN SEMAPHORE_INFORMATION_CLASS Semaphorelnf ormationClass , 

OUT PVOID Semaphorelnformation, 

IN ULONG Semaphorelnf ormationLength, 

OUT PULONG ResultLength OPTIONAL 

); 



Parameters 

SemaphoreHandle 

A handle to a semaphore object. The handle must grant SEMAPHORE_QUERY_STATE access. 

Semaphorelnformation Class 

Specifies the type of semaphore object information to be queried. The permitted val- 
ues are drawn from the enumeration SEMAPHORE_INFORMATION_CLASS, described in the 
following section. 

Semaphorelnformation 

Points to a caller-allocated buffer or variable that receives the requested semaphore 
object information. 

SemaphorelnformationLength 

Specifies the size in bytes of Semaphorelnformation, which the caller should set accord- 
ing to the given SemaphorelnformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Semaphorelnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 



SEMAPHORE_INFORMATION_CLASS 



typedef enum _SEMAPHORE_INFORMATION_CLASS { 
SemaphoreBasicInformation 
} SEMAPHORE_INFORMATION_CLASS ; 



SemaphoreBasicInformation 



typedef struct _SEMAPHORE_BASIC_INFORMATION { 

LONG CurrentCount ; 

LONG MaximumCount ; 

} SEMAPHORE_BASIC_INFORMATION , *PSEMAPHORE_BASIC_INFORMATION ; 

Members 

CurrentCount 

Specifies the current count for the semaphore object. 



Maximum Count 

Specifies the maximum count for the semaphore object. 

Remarks 

None. 



ZwCreateMutant 



ZwCreateMutant creates or opens a mutant object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateMutant ( 

OUT PHANDLE MutantHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 

IN BOOLEAN InitialOwner 

); 
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Parameters 

MutantHandle 

Points to a variable that will receive the mutant object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the mutant object. This parameter 
can be zero, or any combination of the following flags: 

MUTANT_QUERY_STATE Query access 

MUTANT_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a mutant object. 

InitialOwner 

Specifies whether the calling thread should be the initial owner of the mutant. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

CreateMutex. 

Remarks 

CreateMutex exposes most of the functionality of ZwCreateMutant. 



ZwOpenMutant 



ZwOpenMutant opens a mutant object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenMutant ( 

OUT PHANDLE MutantHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Ob j ectAttribUtes 

); 



Parameters 

MutantHandle 

Points to a variable that will receive the mutant object handle if the call is successful. 
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DesiredAccess 

Specifies the type of access that the caller requires to the mutant object. This parameter 
can be zero, or any combination of the following flags: 

MUTANT_QUERY_STATE Query access 

MUTANT_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK is not a valid 
attribute for a mutant object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

OpenMutex. 

Remarks 

OpenMutex exposes most of the functionality of ZwOpenMutant. 



ZwReleaseMutant 



ZwReleaseMutant releases ownership of a mutant object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReleaseMutant ( 

IN HANDLE MutantHandle , 

OUT PULONG PreviousState 

); 



Parameters 

MutantHandle 

A handle to a mutant object. The handle need not grant any specific access. 

PreviousState 

Optionally points to a variable which receives the previous state of the semaphore. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

ReleaseMutex. 

Remarks 

ReleaseMutex exposes most of the functionality of ZwReleaseMutant. 
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ZwQueryMutant 



ZwQueryMutant retrieves information about a mutant object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryMutant ( 

IN HANDLE MutantHandle, 

IN MUTANT_INFORMATION_CLASS Mutantlnf ormationClass , 

OUT PVOID Mutant Information, 

IN ULONG MutantlnformationLength, 

OUT PULONG ResultLength OPTIONAL 

); 

Parameters 

MutantHandle 

A handle to a mutant object. The handle must grant MUTANT_QUERY_STATE access. 

Mutantlnf ormationClass 

Specifies the type of mutant object information to be queried. The permitted values 
are drawn from the enumeration MUTANT INFORMATION CLASS, described in the following 
section. 

Mutantlnformation 

Points to a caller-allocated buffer or variable that receives the requested mutant object 
information. 

MutantlnformationLength 

Specifies the size in bytes of Mutantlnformation, which the caller should set according 
to the given MutantlnformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Mutantlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 
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MUTANT_INFORMATION_CLASS 



typedef enum _MUTANT_INFORMATION_CLASS { 
MutantBasicInformation 
} MUTANT_INFORMATION_CLASS; 



MutantBasicInformation 



typedef Struct _MUTANT_BAS I CONFORMATION { 

LONG SignalState; 

BOOLEAN Owned; 

BOOLEAN Abandoned; 

} MUTANT_BAS I CONFORMATION, *PMUTANT_BASIC_INFORMATION; 

Members 

SignalState 

The signal state of the mutant. A positive value indicates that the mutant is signaled. 

A non-positive value indicates that a thread has recursively acquired the mutant 
(l - SignalState) times. 

Owned 

A boolean indicating whether the mutant is owned by the current thread. 

Abandoned 

A boolean indicating whether the mutant has been abandoned (that is, a thread owned 
the mutant when it terminated). 

Remarks 

None. 



ZwCreateloCompletion 



ZwCreateloCompletion creates or opens an I/O completion object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateloCompletion ( 

OUT PHANDLE IoCompletionHandle , 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 

IN ULONG NumberOfConcurrentThreads 

); 



Parameters 

IoCompletionHandle 

Points to a variable that will receive the I/O completion object handle if the call is 
successful. 
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DesiredAccess 

Specifies the type of access that the caller requires to the I/O completion object. This 
parameter can be zero, or any combination of the following flags: 

I0_C0MPLETI0N_QUERY_STATE Query access 
I0_C0MPLETI0N_M0DIFY_STATE Modify access 

I0_C0MPLETI0N_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK and 
OBJ_PERMANENT are not valid attributes for an I/O completion object. 

NumberOfConcurrentThreads 

Specifies the number of threads that are allowed to execute concurrently. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 



Related Win32 Functions 

CreateloCompletionPort. 



Remarks 

The Win32 function CreateloCompletionPort creates an I/O completion object by 
calling ZwCreateloCompletion and then optionally associates the I/O completion object 
handle and a completion key with a file handle by calling ZwSetlnformationFile with 
a FilelnformationClass of FileCompletionlnformation. 



ZwOpenloCompletion 



ZwOpenloCompletion opens an I/O completion object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenloCompletion ( 

OUT PHANDLE IoCompletionHandle , 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Ob j ectAttributes 

); 



Parameters 

Io CompletionHandle 

Points to a variable that will receive the I/O completion object handle if the call is 
successful. 
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DesiredAccess 

Specifies the type of access that the caller requires to the I/O completion object. This 
parameter can be zero, or any combination of the following flags: 

IO_COMPLETION_QUERY_STATE Query access 
I0_C0MPLETI0N_M0DIFY_STATE Modify access 

IO_COMPLETION_ALL_ACCESS All of the preceding + STANDARD_RIGHTS_ALL 

Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_0PENLINK and 
OBJ_PERMANENT are not valid attributes for an I/O completion object. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 



Remarks 

None. 



ZwSetloCompletion 



ZwSetloCompletion queues an I/O completion message to an I/O completion object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetloCompletion ( 

IN HANDLE IoCompletionHandle , 

IN ULONG CompletionKey , 

IN ULONG CompletionValue, 

IN NTSTATUS Status, 

IN ULONG Information 

); 



Parameters 

IoCompletionHandle 

A handle to an I/O completion object. The handle must grant 
I0_C0MPLETI0N_M0DIFY_STATE access. 

CompletionKey 

Specifies a value to be returned to a caller of ZwRemoveloCompletion via the 
CompletionKey parameter of that routine. 

Completion Value 

Specifies a value to be returned to a caller of ZwRemoveloCompletion via the 
CompletionValue parameter of that routine. 
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Status 

Specifies a value to be returned to a caller of ZwRemoveloCompletion via the parameter 
IoStatusBlock->Status. 

Information 

Specifies a value to be returned to a caller of ZwRemoveloCompletion via the parameter 
IoStatusBlock ^Information. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

PostQueuedCompletionStatus. 

Remarks 

PostQueuedCompletionStatus exposes most of the functionality ol ZwSetloCompletion. 



ZwRemoveloCompletion 



ZwRemoveloCompletion dequeues an I/O completion message from an I/O completion 
object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRemoveloCompletion ( 

IN HANDLE IoCompletionHandle , 

OUT PULONG CompletionKey , 

OUT PULONG CompletionValue, 

OUT PIO_STATUS_BLOCK IoStatusBlock, 

IN PLARGE_INTEGER Timeout OPTIONAL 

); 



Parameters 

Io CompletionHandle 

A handle to an I/O completion object. The handle must grant 
I0_C0MPLETI0N_M0DIFY_STATE access. 

CompletionKey 

Points to a variable that receives the value of the CompletionKey. 

Completion Value 

Points to a variable that receives the value of the CompletionValue. 

IoStatusBlock 

Points to a caller-allocated buffer or variable that receives the I0_STATUS_BL0CK of the 
completed I/O operation. 





1996 CH09 11.24.99 09:55 Page 233 



Synchronization: ZwQueryloCompletion 



233 



Timeout 

Optionally points to a value that specifies the absolute or relative time at which the 
wait is to be timed out. A negative value specifies an interval relative to the current 
time. The value is expressed in units of 100 nanoseconds. Absolute times track any 
changes in the system time; relative times are not affected by system time changes. If 
Timeout is a null pointer, the wait will not timeout. 

Return Value 

Returns STATUS_SUCCESS, STATUS_TIMEOUT or an error status, such as 
STATUS_ACCESS_DENIED or STATUS_INVALID_HANDLE. 

Related Win32 Functions 

GetQueuedCompletionStatus. 

Remarks 

GetQueuedCompletionStatus exposes most of the functionality of 

ZwRemoveloCompletion. 



ZwQueryloCompletion 



ZwQueryloCompletion retrieves information about an I/O completion object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryloCompletion ( 

IN HANDLE IoCompletionHandle , 

IN I0_C0MPLETI0N_INF0RMATI0N_CLASS IoCompletionlnf ormationClass , 

OUT PVOID IoCompletionlnformation, 

IN ULONG IoCompletionlnformationLength, 

OUT PULONG ResultLength OPTIONAL 

); 



Parameters 

IoCompletionHandle 

A handle to an I/O completion object. The handle must grant 
1 0_C0MP L ET 1 0N_QU E R Y_ST AT E access. 

Io Completionlnformation Class 

Specifies the type of I/O completion object information to be queried. The permitted 
values are drawn from the enumeration I0_C0MPLETI0N_INF0RMATI0N_CLASS, described 
in the following section. 

Io Completionlnformation 

Points to a caller-allocated buffer or variable that receives the requested I/O comple- 
tion object information. 
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Io CompletionlnformationLength 

Specifies the size in bytes of IoCompletionlnf ormation, which the caller should set 
according to the given IoCompletionlnformationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
IoCompletionlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 



IO_COMPLETION_INFORMATION_CLASS 



typedef enum _I0_C0MPLETI0N_INF0RMATI0N_CLASS { 
IoCompletionBasic Information 
} I0_C0MPLETI0N_INF0RMATI0N_CLASS ; 



IoCompletionBasicInformation 



typedef struct _I0_C0MPLETI0N_BASIC_INF0RMATI0N { 

LONG SignalState; 

} I0_C0MPLETI0N_BASIC_INF0RMATI0N , *PI0_C0MPLETI0N_BASIC_INF0RMATI0N ; 

Members 

SignalState 

The signal state of the I/O completion object. A positive value indicates that the I/O 
completion object is signaled. 

Remarks 

None. 



ZwCreateEventPair 



ZwCreateEventPair creates or opens an event pair object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateEventPair ( 
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OUT PHANDLE EventPairHandle , 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 

Parameters 

EventPairHandle 

Points to a variable that will receive the event pair object handle if the call is 
successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the event pair object. This para- 
meter can be zero or STANDARD_RIGHTS_ALL. 

Obj ectAttributes 

Points to a structure that specifies the object’s attributes. 0BJ_0PENLINK is not a valid 
attribute for an event pair object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

None. 

Remarks 

An event pair object is an object constructed from two KEVENT structures which are 
conventionally named “High” and “Low.” They are optimized for fast client server 
interactions and are not often used by the operating system, having been superseded by 
the LPC port mechanism. 

pstat.exe and kdextx86.dll report some threads as having a wait reason of 
“EventPairLow,” but this is misleading. The numeric value of the wait reason for these 
threads is OxF, and newer versions of ntddk.h translate this as “WrQueue” (0xE is 
“WrEventPair”) — which better reflects the true reason for the wait, pstat and kdextx86 
translate 0xE as “WrEventPairHigh” and 0xF as “WrEventPairLow .” 



ZwOpenEventPair 



ZwOpenEventPair opens an event pair object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenEventPair( 

OUT PHANDLE EventPairHandle, 

IN ACCESS_MASK DesiredAccess, 

IN POBJECT_ATTRIBUTES Obj ectAttributes 

); 
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Parameters 

EventPairHandle 

Points to a variable that will receive the event pair object handle if the call is 
successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the event pair object. This para- 
meter can be zero or STANDARD_RIGHTS_ALL. 

ObjectAttributes 

Points to a structure that specifies the object’s attributes. OBJ OPENLINK is not a valid 
attribute for an event pair object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwWaitLowEventPair 



ZwWaitLowEventPair waits for the low event of an event pair to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWaitLowEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

EventPairHandle 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 



None. 
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Remarks 

The two events in an event pair are named “Low” and “High.” ZwWaitLowEventPair 
waits for the Low event to be set. The EventPairHandle itself is not directly waitable. 



ZwWaitHighEventPair 



ZwWaitHighEventPair waits for the high event of an event pair to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWaitHighEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

EventPairHandle 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The two events in an event pair are named “Low” and “High.” ZwWaitHighEventPair 
waits for the High event to be set. The EventPairHandle itself is not directly waitable. 



ZwSetLowWaitHighEventPair 



ZwSetLowWaitHighEventPair signals the low event of an event pair and waits for the 
high event to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetLowWaitHighEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

Even tPa irHan d le 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The two events in an event pair are named “Low” and “High.” 

ZwSetLowWaitHighEventPair signals the Low event and waits for the High event to be 
set. If a thread is waiting for the Low event, the system switches immediately to that 
thread rather choosing a thread to run based on scheduling priorities. This is the same 
mechanism that is used by LPC ports to improve the performance of client server 
interactions. 



ZwSetHighWaitLowEventPair 



ZwSetHighWaitLowEventPair signals the high event of an event pair and waits for the 
low event to become signaled. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetHighWaitLowEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

EventPairHandle 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The two events in an event pair are named “Low” and “High.” 

ZwSetHighWaitLowEventPair signals the High event and waits for the Low event to be 
set. If a thread is waiting for the High event, the system switches immediately to that 
thread rather than choosing a thread to run based on scheduling priorities. This is the 
same mechanism hat is used by LPC ports to improve the performance of client server 
interactions. 





1996 CH09 



11.24. 99 



09:55 



Page 239 



Synchronization: ZwSetHighEventPair 



239 



ZwSetLowEventPair 



ZwSetLowEventPair signals the low event of an event pair object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetLowEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

EventPairHandle 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 



Remarks 

The two events in an event pair are named “Low” and “High.” ZwSetLowEventPair 
signals the Low event. 



ZwSetHighEventPair 



ZwSetHighEventPair signals the high event of an event pair object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetHighEventPair ( 

IN HANDLE EventPairHandle 

); 



Parameters 

EventPairHandle 

A handle to an event pair object. The handle must grant SYNCHRONIZE access. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS INVALID HANDLE. 
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Related Win32 Functions 

None. 



Remarks 

The two events in an event pair are named “Low” and “High.” ZwSetHighEventPair 
signals the High event. 
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Time 



The system services described in this chapter are loosely concerned with time and 
timing. 



ZwQuerySystemTime 



ZwQuerySystemTime retrieves the system time. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerySystemTime ( 

OUT PLARGE_INTEGER CurrentTime 

); 

Parameters 

CurrentTime 

Points to a variable that receives the current time of day in the standard time format 
(that is, the number of 100-nanosecond intervals since January 1, 1601). 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

GetSystemTime and GetSystemTimeAsFileTime read from the KUSER_SHARED_DATA page. 
This page is mapped read-only into the user mode range of the virtual address and 
read- write in the kernel range. The system clock tick updates the system time, which 
is stored in this page directly. Reading the system time from this page is faster than 
calling ZwQuerySystemTime. 

The KUSER SHARED_DATA structure is defined in the Windows 2000 versions of ntddk.h. 
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ZwSetSystemTime 



ZwSetSystemTime sets the system time. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetSystemTime ( 

IN PLARGE_INTEGER NewTime, 

OUT PLARGE_INTEGER OldTime OPTIONAL 

); 

Parameters 

NewTime 

Points to a variable that specifies the new time of day in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

OldTime 

Optionally points to a variable that receives the old time of day in the standard time 
format (that is, the number of 100-nanosecond intervals since January 1, 1601). 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

SetSystemTime. 

Remarks 

SeSystemtimePrivilege is required to set the system time. 



ZwQueryPerformanceCounter 



ZwQueryPerformanceCounter retrieves information from the high-resolution 
performance counter. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryPerformanceCounter ( 

OUT PLARGE_INTEGER Perf ormanceCount , 

OUT PLARGE_INTEGER Perf ormanceFrequency OPTIONAL 

); 



Parameters 

PerformaticeCount 

Points to a variable that receives the current value of the performance counter. 
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PeiformanceFrequency 

Optionally points to a variable that receives the frequency of the performance counter 
in units of counts per second. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

QueryPerformanceCounter, QueryPerf ormanceFrequency. 

Remarks 

Collectively QueryPerformanceCounter and QueryPerformanceFrequency expose the full 
functionality of ZwQueryPerformanceCounter. 



ZwSetTimerResolution 



ZwSetTimerResolution sets the resolution of the system timer. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetTimerResolution ( 

IN ULONG RequestedResolution, 

IN BOOLEAN Set, 

OUT PULONG ActualResolution 

); 



Parameters 

RequestedResolution 

The requested timer resolution in units of 100-nanoseconds. 



Set 

Specifies whether the requested resolution should be established or revoked. 

ActualResolution 

Points to a variable that receives the actual timer resolution in units of 
1 00-nanoseconds. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_TIMER_RESOLUTION_NOT_SET. 

Related Win32 Functions 

timeBeginPeriod, timeEndPeriod. 



Remarks 

None. 
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ZwQueryTimerResolution 



ZwQueryTimerResolution retrieves information about the resolution of the system 
timer. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryTimerResolution ( 

OUT PULONG CoarsestResolution, 

OUT PULONG FinestResolution, 

OUT PULONG ActualResolution 

); 



Parameters 

CoarsestResolution 

Points to a variable that receives the coarsest timer resolution, which can be set in 
units of 100-nanoseconds. 

FinestResolution 

Points to a variable that receives the finest timer resolution, which can be set in units 
of 100-nanoseconds. 

ActualResolution 

Points to a variable that receives the actual timer resolution in units of 
1 00-nanoseconds. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwDelayExecution 



ZwDelayExecution suspends the execution of the current thread for a specified interval. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDelayExecution ( 

IN BOOLEAN Alertable, 

IN PLARGE_INTEGER Interval 

); 



Parameters 

Alertable 

A boolean specifying whether the delay can be interrupted by the delivery of 
a user APC. 
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Interval 

Points to a value that specifies the absolute or relative time at which the delay is to 
end. A negative value specifies an interval relative to the current time. The value is 
expressed in units of 100 nanoseconds. Absolute times track any changes in the system 
time; relative times are not affected by system time changes. 

Return Value 

Returns STATUS_SUCCESS, STATUS_ALERTED, STATUS_USER_APC, or an error status. 

Related Win32 Functions 

Sleep, SleepEx. 

Remarks 

SleepEx exposes most of the functionality ot ZwDelayExecution. 



ZwYieldExecution 



ZwYieldExecution yields the use of the processor by the current thread to any other 
thread that is ready to use it. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwYieldExecution ( 

VOID 

); 



Parameters 

None 



Return Value 

Returns STATUS_SUCCESS or STATUS_N0_Y I ELDPER FORMED. 

Related Win32 Functions 

SwitchToThread. 



Remarks 

SwitchToThread exposes the full functionality of ZwYieldExecution. 



ZwGetTickCount 



ZwGetTickCount retrieves the number of milliseconds that have elapsed since the system 
booted. 

NTSYSAPI 

ULONG 

NTAPI 

ZwGetTickCount ( 

VOID 

); 
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Parameters 

None. 

Return Value 

Returns the number of milliseconds that have elapsed since the system was booted. 

Related Win32 Functions 

None. 

Remarks 

GetTickCount reads from the KUSER_SHARED_DATA page. This page is mapped read-only 
into the user mode range of the virtual address and read- write in the kernel range. The 
system clock tick updates the system tick count, which is stored in this page directly. 
Reading the tick count from this page is faster than calling ZwGetTickCount. 



The KUSER SHARED DATA structure is defined in the Windows 2000 versions of ntddk.h. 
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Execution Profiling 



The system services described in this chapter create and manipulate objects that gather 
execution profiling information. 



KPROFILE_SOURCE 



typedef enum _KPROFILE_SOURCE { 

Prof ileTime 
} KPROFILE_SOURCE; 

Remarks 

KPROFILE_SOURCE is defined in ntddk.h, and the definition there includes additional 
values. However only Prof ileTime is implemented for the Intel family of processors 
by the standard Hardware Abstraction Layer (HAL) (named HAL. DLL on the installa- 
tion CD). 



Z wCre ateProfile 



ZwCreateProf ile creates a profile object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateProfile( 

OUT PHANDLE Prof ileHandle, 

IN HANDLE ProcessHandle, 

IN PVOID Base, 

IN ULONG Size, 

IN ULONG BucketShift, 

IN PULONG Buffer, 

IN ULONG BufferLength, 

IN KPROFILE_SOURCE Source, 

IN ULONG ProcessorMask 

); 
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Parameters 

ProfileHandle 

Points to a variable that will receive the profile object handle if the call is successful. 

ProcessHandle 

A handle of a process object, representing the process for which profile data should be 
gathered. The handle must grant PROCESS_QUERY_INFORMATION access. If this handle is a 
null pointer, profile data is gathered for the system. 

Base 

The base address of a region of memory to profile. 

Size 

The size, in bytes, of a region of memory to profile. 

BucketShift 

Specifies the number of bits of right-shift to be applied to the instruction pointer 
when selecting the bucket to be incremented. Valid shift sizes are 0 to 31; if size is 
greater than 0x10000, the shift size must be in the range 2 to 31. 

Buffer 

Points to a caller-allocated buffer or variable that receives an array of ULONG values, one 
per bucket, representing the hit count for each bucket. 

BufferLength 

The size, in bytes, of Buffer. 

Source 

The source of the event that triggers sampling of the instruction pointer. 

ProcessorMask 

A bit array of flags specifying whether profiling information should be gathered on the 
corresponding processor. If ProcessorMask is zero, profiling information is gathered on 
all active processors. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_ACCESS_DENIED, STATUS_PRIVILEGE_NOT_HELD, or STATUS_BUFFER_T00_SMALL. 

Related Win32 Functions 



None. 
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Remarks 

SeSystemProf ilePrivilege is required to profile the system. 

A profile source is a source of events. When an event from the source occurs, the 
processor instruction pointer (Eip) is sampled, and if it lies in the range Base to Base+Size 
of an active (started) profile object, the Buffer element at (Eip - Base) » 
BucketShif t is incremented. 

Example 11.1 demonstrates the use of the profiling APIs to profile the kernel. 



ZwSetlntervalProfile 



ZwSetlntervalProfile sets the interval between profiling samples for the specified 
profiling source. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlntervalProfile ( 

IN ULONG Interval, 

IN KPROFILE_SOURCE Source 

); 



Parameters 

Interval 

Specifies the interval between profiling samples. 

Source 

Specifies the source of profiling events to be set. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

For the Prof ileTime source, the interval unit is 100 nanoseconds; for other sources 
the interval might be the number of events from the event source to ignore between 
sampling. 



ZwQuerylntervalProfile 



ZwQuerylntervalProfile retrieves the interval between profiling samples for the 
specified profiling source. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylntervalProfile ( 
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IN KPROFILESOURCE Source, 

OUT PULONG Interval 

); 

Parameters 

Source 

Specifies the source of profiling events to be queried. 

Interval 

Points to a variable that receives the interval between profiling samples. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwStartProfile starts the collection of profiling data. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwStartProfile ( 

IN HANDLE Prof ileHandle 
); 

Parameters 

ProfileHandle 

A handle to a profile object. The handle must grant PROFILE_START_STOP access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_ACCESS_DENIED, STATUS_PROFILING_NOT_STOPPED, or 
STATUS_P ROF I L I NG_AT_L I M I T. 

Related Win32 Functions 



e 




e 



None. 




Remarks 

None. 





1996 CH11 11/19/99 12:27 PM Page 5 



Execution Profiling: Example 11.1 



ZwStopProfile 



ZwStopProf ile stops the collection of profiling data. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwStopProfile( 

IN HANDLE Prof ileHandle 

); 



Parameters 

ProjileHandle 

A handle to a profile object. The handle must grant PROFILE_START_STOP access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_ACCESS_DENIED, or STATUS_PROF I L I NG_NOT_STARTED. 

Related Win32 Functions 

None. 

Remarks 

None. 



Example 11.1: Profiling the Kernel 



#include "ntdll.h" 

#include <stdio.h> 

#include <imagehlp.h> 

HANDLE hWakeup; 

PULONG LoadDrivers( ) 

{ 

ULONG n = 0x1000; 

PULONG p = new UL0NG[ n] ; 

while (NT: :ZwQuerySystemInformation(NT: :SystemModuleInformation, p, n, 0) 
== STATUS_INFO_LENGTH_MISMATCH) 
delete [] p, p = new UL0NG[n = n * 2]; 
return p; 



BOOL WINAPI ConsoleCtrlHandler(DWORD dwCtrlType) 

{ 

return dwCtrlType == CTRL_C_EVENT ? SetEvent (hWakeup) : FALSE; 

} 



int main() 

{ 



ULONG shift = 3; 







1996 CH11 11/19/99 12:27 PM Page 6 



6 Execution Profiling: Example 11.1 



EnablePrivilege(SE_SYSTEM_PROFILE_NAME) ; 

PULONG modules = LoadDrivers( ) ; 

NT : :ZwSetIntervalProfile( 10000, NT : : Prof ileTime) ; 

NT: :PSYSTEM_MODULE_INFORMATION m 

= NT: :PSYSTEM_MODULE_INFORMATION (modules +1); 

PHANDLE h = new HANDLE[ *modules] ; 

PULONG* p = new PUL0NG[ *modules] ; 

for (ULONG i = 0; i < *modules; i++) { 

ULONG n = ( m [ i ] .Size » (shift - 2)) + 1; 

p[i] = PULONG (VirtualAlloc ( 0 , n, MEM_COMMIT, PAGE_READWRITE) ) ; 

NT: :ZwCreateProf ile(h + i, 0, m[i].Base, m[i].Size, 

shift, p[i], n, NT: : Prof ileTime, 0); 

NT : :ZwStartProfile(h[i] ) ; 

} 

hWakeup = CreateEvent (0, FALSE, FALSE, 0); 
SetConsoleCtrlHandler(ConsoleCtrlHandler, TRUE) ; 
printf ( "collecting. . . \n" ) ; 

WaitForSingleObject (hWakeup, INFINITE) ; 
for (i = 0; i < *modules; i++) { 

NT : :ZwStopProf ile(h[i] ) ; 

CloseHandle(h[i] ) ; 

} 

SymInitialize(0, 0, FALSE); 

SymSetOptions (SymGetOptions ( ) | SYMOPT_DEFERRED_LOADS | SYMOPT_UNDNAME ) 

for (i = 0; i < *modules; i++) { 

SymLoadModule(0, 0, m[i] . ImageName, 

m[i] . ImageName + m[i] .ModuleNameOff set , 

UL0NG(m[i] .Base) , m[i].Size); 

printf ( "%s\n" , m[i] . ImageName + m [ i ] .ModuleNameOff set) ; 

ULONG n = (m[i].Size » shift) + 1; 

for (ULONG j = 0; j < n; j++) { 

if ( p [ i ] [ j ] ! = 0) { 

IMAGEHLP_SYMBOL symbol[10]; 

symbol[0] .SizeOfStruct = sizeof symbol[0]; 

symbol[0] .MaxNameLength = sizeof symbol - sizeof symbol[0]; 
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ULONG disp = 0; 

SymGetSymFromAddr (0, UL0NG(m[i] .Base) + (j « shift), 

&disp, symbol); 

printf ( "%61d %s+0x%lx\n" , p[i][j], symbol[0] .Name, disp); 

} 

} 

SymUnloadModule(0, UL0NG(m[i] .Base) ) ; 

VirtualFree(p[i] , 0, MEM_RELEASE) ; 

} 

SymCleanup(0) ; 

delete [] m; 
delete [] h; 
delete [] p; 

return 0; 

} 

Example 11.1 implements broadly similar functionality to that found in the resource 
kit utility kernprof.exe. It uses ZwQuerySystemlnformation to obtain the size and base 
address of the kernel modules and then creates and starts a profile object for each 
module. Data is gathered until interrupted by control-C and then the imagehlp library 
is used to help dump the collected data. 

It is only useful for a profile to cover the code sections of a module, but it is harmless 
(if wasteful of buffer space) if the profile covers the whole module. 

The rounding of the sampled instruction pointer that results from applying the 
BucketShift has the consequence that some samples are attributed to the wrong 
symbolic name. This problem is compounded in Windows 2000 because most of the 
executable modules have been through an optimization process that reorders the 
instructions of the executable to improve locality of reference; this means that the 
instructions that implement a routine are no longer contiguous in memory. Although 
the symbol files contain information about this reordering (the omap data), the inci- 
dence of false attribution is still quite high. 

In the section of winbase.h that defines the values of the dwCreationFlag parameter 
of CreateProcess, the value PROFILE_USER also appears. If this value is specified when 
calling CreateProcess then, when kernel32.dll is initialized in the new process, 
psapi.dll is loaded and creates profiles for the user mode modules of the process, and 
when the process ends the collected data is written to the file “profile. out.” Some para- 
meters of the profiling performed by psapi.dll can be controlled by the resource kit 
utility profile.exe, which creates a named shared memory region to hold the parame- 
ters and then starts the program to be profiled with the PROFILE_USER flag; psapi.dll 
checks for the presence of this named shared memory region and, if found, customizes 
its behavior accordingly. 
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12 

Ports (Local 
Procedure Calls) 



The system services described in this chapter create and manipulate port objects. Port 
objects are used to implement the Local Procedure Call (LPC) mechanism. 

Port objects are not directly exposed via the Win32 API, but they are used to imple- 
ment the “ncalrpc” Remote Procedure Call (RPC) transport. The RPC run-time 
library greatly simplifies the use of port objects, but the library (rpcrt4.dll) imports 
functions from kernel32.dll, and so it can only be used by Win32 applications. 

Port objects must be used explicitly to receive and process messages sent by the oper- 
ating system, such as debug and exception messages. Example D.4 in Appendix D, 
“Exceptions and Debugging,” demonstrates the use of some of the port functions to 
handle debug event messages. 



PORT_MESSAGE 



typedef struct _P0RT_MESSAGE { 

USHORT DataSize; 

USHORT MessageSize; 

USHORT MessageType; 

USHORT VirtualRangesOffset ; 

CLIENT_ID Clientld; 

ULONG Messageld; 

ULONG SectionSize; 

// UCHAR Data[ ] ; 

} P0RT_MESSAGE , *PP0RT_MESSAGE; 

Members 

DataSize 

The size in bytes of the data immediately following the P0RT_MESSAGE structure. 

MessageSize 

The size in bytes of the message; this includes the size of the P0RT_MESSAGE structure, 
the following data, and any additional trailing space that could be used to hold 
further data. 
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MessageType 

Specifies the type of the message. The permitted values are drawn from the enumera- 
tion LPC TYPE: 



typedef enum _LPC_TYPE { 

LPC_NEW_MESSAGE , 
LPC_REQUEST, 

LPC_REPLY, 
LPC_DATAGRAM, 
LPC_L0ST_REPLY , 
LPC_P0RT_CL0SED , 
LPC_CLIENT_DIED, 
LPC_EXCEPTI0N , 
LPC_DEBUG_EVENT , 
LPC_ERROR_EVENT , 
LPC_C0NNECTI0N_REQUEST 
} LPC_TYPE; 



// A new message 

// A request message 

// A reply to a request message 

// 

// 

// Sent when port is deleted 
// Messages to thread termination ports 
// Messages to thread exception port 
// Messages to thread debug port 
// Used by ZwRaiseHardError 
// Used by ZwConnectPort 



VirtualRanges Offset 

The offset, in bytes, from the start of the P0RT_MESSAGE structure to an array of virtual 
address ranges. The format of the virtual address ranges is a ULONG count of the number 
of ranges immediately followed by an array of PVOID/ ULONG address/length pairs. 



Clientld 

The client identifier (thread and process identifiers) of the sender of the message. 



Messageld 

A numeric identifier of the particular instance of the message. 



SectionSize 

The size, in bytes, of the section created by the sender of the message. 



Data 

The data of the message. 

Remarks 

All messages sent via ports begin with a P0RT_MESSAGE header. 

When initializing a P0RT_MESSAGE structure, the MessageType should always be set to 
LPC_NEW_MESSAGE; when replying to a received message, the MessageType and 
Messageld of the received message should be copied to the reply message. The 
MessageType is updated by the system when the message is transferred. 

The remaining message types can only be generated by kernel mode code calling 
LpcRequestPort or LpcRequestWaitReplyPort. 

The amount of data that can be transferred with the P0RT_MESSAGE is limited to about 
300 bytes. 
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PORT_SECTION_ WRITE 



typedef struct _P0RT_SECTI0N_WRITE { 

ULONG Length; 

HANDLE SectionHandle; 

ULONG SectionOff set ; 

ULONG ViewSize; 

PVOID ViewBase; 

PVOID TargetViewBase; 

} PORT_SECTION_WRITE, *PPORT_SECTION_WRITE ; 

Members 

Length 

The size, in bytes, of the PORT_SECTION_WRITE structure. 

SectionHandle 

A handle to a section object. The handle must grant SECTION_MAP_WRITE and 
SECTION_MAP_READ access. 

SectionOffset 

The offset in the section to map a view for the port data area. The offset must be 
aligned with the allocation granularity of the system. 

ViewSize 

The size, in bytes, of the view. 

ViewBase 

The base address of the view in the creator of the port section. 

TargetViewBase 

The base address of the view in the process connected to the port. 

Remarks 

The creator of the port section initializes the members Length, SectionHandle, 
SectionOffset and ViewSize; the other members are initialized by the system. 

Port sections can be used to transfer data that is too large to fit in a port message. The 
system maps a view of the section in the peer process and makes the base address of 
the view available to the creator of the port section. The creator of the port section 
can then either write data to the view in self-relative format, or can fix up any point- 
ers in the data so that they are valid in the context of the peer process. 



PORT_SECTION_READ 



typedef struct _P0RT_SECTI0N_READ { 

ULONG Length; 

ULONG ViewSize; 

ULONG ViewBase; 

} P0RT_SECTI0N_READ , *PP0RT_SECTI0N_READ; 
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Members 

Length 

The size, in bytes, of the P0RT_SECTI0N_READ structure. 

ViewSize 

The size, in bytes, of the view. 

ViewBase 

The base address of the view. 

Remarks 

The peer of a process that creates a port section learns about the base address and view 
size of the section from the members of the PORT SECTION READ structure. 



ZwCreatePort 



ZwCreatePort creates a port object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreatePort ( 

OUT PHANDLE PortHandle, 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 
IN ULONG MaxDataSize, 

IN ULONG MaxMessageSize, 

IN ULONG Reserved 

); 



Parameters 

PortHandle 

Points to a variable that will receive the port object handle if the call is successful. 

ObjectAttributes 

Points to a structure that specifies the object’s attributes. OBJ_KERNEL_HANDLE, 
0BJ_0PENLINK, OBJ_OPENIF, 0BJ_EXCLUSIVE, 0BJ_PERMANENT, and 0BJ_INHERIT are not 
valid attributes for a port object. 

MaxDataSize 

The maximum size, in bytes, of data that can be sent through the port. 

MaxMessageSize 

The maximum size, in bytes, of a message that can be sent through the port. 

Reserved 

Not used. 
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Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

None. 



Remarks 

ZwCreatePort verifies that (MaxDataSize <= 0x104) and 
(MaxMessageSize <= 0x148). 



ZwCreateWaitablePort 



ZwCreateWaitablePort creates a waitable port object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateWaitablePort ( 

OUT PHANDLE PortHandle, 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN ULONG MaxDataSize, 

IN ULONG MaxMessageSize, 

IN ULONG Reserved 

); 



Parameters 

PortHandle 

Points to a variable that will receive the waitable port object handle if the call is 
successful. 

ObjectAttributes 

Points to a structure that specifies the object’s attributes. OBJ_KERNEL_HANDLE, 
0BJ_0PENLINK, 0BJ_0PENIF, 0BJ_EXCLUSIVE, 0BJ_PERMANENT, and 0BJ_INHERIT are not 
valid attributes for a waitable port object. 

MaxDataSize 

The maximum size, in bytes, of data that can be sent through the port. 

MaxMessageSize 

The maximum size, in bytes, of a message that can be sent through the port. 

Reserved 

Not used. 

Return Value 



Returns STATUS SUCCESS or an error status. 
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Related Win32 Functions 

None. 

Remarks 

ZwCreateWaitablePort verifies that (MaxDataSize <= 0x104) and 
(MaxMessageSize <= 0x148). 

Waitable ports can be connected to with ZwSecureConnectPort and messages can be 
sent and received with ZwReplyWaitReceivePort or ZwReplyWaitReceivePortEx. The 

other port functions cannot be used with waitable ports. Requests can only be sent to 
waitable ports by kernel mode components calling the routines LpcRequestPort or 
LpcRequestWait Reply Port. 

The routine ZwCreateWaitablePort is only present in Windows 2000. 



ZwConnectPort 



ZwConnectPort creates a port connected to a named port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwConnectPort( 

OUT PHANDLE PortHandle, 

IN PUNIC0DE_STRING PortName, 

IN PSECURITY_QUALITY_OF_SERVICE SecurityQos, 

IN OUT PP0RT_SECTI0N_WRITE WriteSection OPTIONAL, 

IN OUT PP0RT_SECTI0N_READ ReadSection OPTIONAL, 

OUT PUL0NG MaxMessageSize OPTIONAL, 

IN OUT PV0ID ConnectData OPTIONAL, 

IN OUT PUL0NG ConnectDataLength OPTIONAL 

); 



Parameters 

PortHandle 

Points to a variable that will receive the port object handle if the call is successful. 

PortName 

Points to a structure that specifies the name of the port to connect to. 

SecurityQos 

Points to a structure that specifies the level of impersonation available to the port 
listener. 

WriteSection 

Optionally points to a structure describing the shared memory region used to send 
large amounts of data to the listener; if the call is successful, this will be updated. 
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Read Section 

Optionally points to a caller-allocated buffer or variable that receives information on 
the shared memory region used by the listener to send large amounts of data to the 
caller. 

MaxMessageSize 

Optionally points to a variable that receives the size, in bytes, of the largest message 
that can be sent through the port. 

ConnectData 

Optionally points to a caller-allocated buffer or variable that specifies connect data to 
send to the listener, and receives connect data sent by the listener. 

ConnectDataLength 

Optionally points to a variable that specifies the size, in bytes, of the connect data to 
send to the listener, and receives the size of the connect data sent by the listener. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_0BJECT_NAME_N0T_F0UND, STATUS_P0RT_C0NNECTI0N_REFUSED, or 
STATUS_INVALID_PORT_HANDLE. 

Related Win32 Functions 

Example 12.1 demonstrates the connection establishment process. 

Remarks 

None. 



ZwSecureConnectPort 



ZwSecureConnectPort creates a port connected to a named port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSecureConnectPort ( 

OUT PHANDLE PortHandle, 

IN PUNICODE_STRING PortName, 

IN PSECURITY_QUALITY_OF_SERVICE SecurityQos, 

IN OUT PP0RT_SECTI0N_WRITE WriteSection OPTIONAL, 

IN PSID ServerSid OPTIONAL 

IN OUT PP0RT_SECTI0N_READ ReadSection OPTIONAL, 

OUT PULONG MaxMessageSize OPTIONAL, 

IN OUT PVOID ConnectData OPTIONAL, 

IN OUT PULONG ConnectDataLength OPTIONAL 

); 
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Parameters 

PortHandle 

Points to a variable that will receive the port object handle if the call is successful. 

PortName 

Points to a structure that specifies the name of the port to connect to. 

Security Qos 

Points to a structure that specifies the level of impersonation available to the port 
listener. 

WriteSection 

Optionally points to a structure describing the shared memory region used to send 
large amounts of data to the listener; if the call is successful, this will be updated. 

ServerSid 

Optionally points to a structure that specifies the expected SID of the process listening 
for the connection. 

ReadSection 

Optionally points to a caller-allocated buffer or variable that receives information on 
the shared memory region used by the listener to send large amounts of data to the 
caller. 

MaxMessageSize 

Optionally points to a variable that receives the size, in bytes, of the largest message 
that can be sent through the port. 

ConnectData 

Optionally points to a caller-allocated buffer or variable that specifies connect data to 
send to the listener, and receives connect data sent by the listener. 

ConnectDataLength 

Optionally points to a variable that specifies the size, in bytes, of the connect data to 
send to the listener, and receives the size of the connect data sent by the listener. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_0BJ ECT_NAME_N0T_F0UND, STATUS_P0RT_C0NNECTI0N_REFUSED, 
STATUS_INVALID_PORT_HANDLE, or STATUS_SERVER_SID_MISMATCH. 

Related Win32 Functions 



None. 
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)Remarks 

The routine ZwSecureConnectPort is only present in Windows 2000. 

The ServerSid parameter is used to ensure that the named port to which the connec- 
tion will be made is being listened to by a process whose primary token identifies the 
TokenUser as ServerSid. This prevents messages containing sensitive data from being 
sent to an untrusted user who has managed somehow to usurp use of the port name. 



ZwListenPort 



ZwListenPort listens on a port for a connection request message. 

NTSYSAPI 
NTSTATUSNTAPI 
ZwListenPort ( 

IN HANDLE PortHandle, 

OUT PP0RT_MESSAGE Message 

); 

Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Message 

Points to a caller-allocated buffer or variable that receives the connect message sent to 
the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The message type of the received message is LPC_CONNECTION_REQUEST.The message 
data is the connect data specified in the call to ZwConnectPort. 



ZwAcceptConnectPort 



ZwAcceptConnectPort accepts or rejects a connection request. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAcceptConnectPort ( 

OUT PHANDLE PortHandle, 

IN ULONG Portldentifier, 

IN PP0RT_MESSAGE Message, 

IN BOOLEAN Accept, 

IN OUT PP0RT_SECTI0N_WRITE WriteSection OPTIONAL, 

IN OUT PP0RT_SECTI0N_READ ReadSection OPTIONAL 

); 
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Parameters 

PortHandle 

Points to a variable that will receive the port object handle if the call is successful. 

Portldentifier 

A numeric identifier to be associated with the port. 

Message 

Points to a caller- allocated buffer or variable that identifies the connection request and 
contains any connect data that should be returned to requestor of the connection. 

Accept 

Specifies whether the connection should be accepted or not. 

WriteSection 

Optionally points to a structure describing the shared memory region used to send 
large amounts of data to the requestor; if the call is successful, this will be updated. 

ReadSection 

Optionally points to a caller-allocated buffer or variable that receives information on 
the shared memory region used by the requestor to send large amounts of data to the 
caller. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_REPLY_MESSAGE_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwCompleteConnectPort 



ZwCompleteConnectPort completes the port connection process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCompleteConnectPort ( 

IN HANDLE PortHandle 

); 
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Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_INVALID_PORT_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwRequestPort 



ZwRequestPort sends a request message to a port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRequestPort ( 

IN HANDLE PortHandle, 

IN PP0RT_MESSAGE RequestMessage 

); 



Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

RequestMessage 

Points to a caller- allocated buffer or variable that specifies the request message to send 
to the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_PORT_DISCONNECTED. 

Related Win32 Functions 

None. 

Remarks 

None. 
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ZwRequestWaitReplyPort 



ZwRequestWaitReplyPort sends a request message to a port and waits for a reply 
message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRequestWaitReplyPort ( 

IN HANDLE PortHandle, 

IN PP0RT_MESSAGE RequestMessage , 

OUT PP0RT_MESSAGE ReplyMessage 

); 



Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

RequestMessage 

Points to a caller-allocated buffer or variable that specifies the request message to send 
to the port. 

ReplyMessage 

Points to a caller-allocated buffer or variable that receives the reply message sent to the 
port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_PORT_DISCONNECTED, STATUS_THREAD_I S_T ERMINATING, STATUS_REPLY_MES - 
SAGE_MISMATCH or STATUS_LPC_REPLY_LOST. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwReplyPort 



ZwReplyPort sends a reply message to a port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReplyPort ( 

IN HANDLE PortHandle, 

IN PPORTJVIESSAGE ReplyMessage 

); 







1996 Chi 2 12/2/99 9:30 AM 



Page 267 



Ports (Local Procedure Calls): ZwReplyWaitReplyPort 267 



Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

ReplyMessage 

Points to a caller-allocated buffer or variable that specifies the reply message to send to 
the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE or 
STATUS_REPLY_MESSAGE_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwReplyWaitReplyPort 



ZwReplyWaitReplyPort sends a reply message to a port and waits for a reply message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReplyWaitReplyPort ( 

IN HANDLE PortHandle, 

IN OUT PP0RT_MESSAGE ReplyMessage 

); 



Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

ReplyMessage 

Points to a caller-allocated buffer or variable that specifies the reply message to send to 
the port and receives the reply message sent to the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_REPLY_MESSAGE_MISMATCH. 

Related Win32 Functions 



None. 
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Remarks 

None. 



ZwReplyWaitReceivePort 



ZwReplyWaitReceivePort optionally sends a reply message to a port and waits for a 
message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReplyWaitReceivePort ( 

IN HANDLE PortHandle, 

OUT PULONG Portldentifier OPTIONAL, 

IN PPORTJVIESSAGE ReplyMessage OPTIONAL, 

OUT PP0RT_MESSAGE Message 

); 



Parameters 

PortHandle 

A handle to either a port object or a waitable port object. The handle need not grant 
any specific access. 

Portldentifier 

Optionally points to a variable that receives a numeric identifier associated with the 
port. 

ReplyMessage 

Optionally points to a caller-allocated buffer or variable that specifies the reply mes- 
sage to send to the port. 

Message 

Points to a caller-allocated buffer or variable that receives the message sent to the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_REPLY_MESSAGE_MISMATCH. 

Related Win32 Functions 

None. 

Remarks 

None. 
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ZwReplyWaitReceivePortEx 



ZwReplyWaitReceivePortEx optionally sends a reply message to a port and waits for a 
message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReplyWaitReceivePortEx ( 

IN HANDLE PortHandle, 

OUT PULONG Portldentifier OPTIONAL, 

IN PPORTJVIESSAGE ReplyMessage OPTIONAL, 

OUT PPORT_MESSAGE Message, 

IN PLARGE_INTEGER Timeout 

); 

Parameters 

PortHandle 

A handle to either a port object or a waitable port object. The handle need not grant 
any specific access. 

Portldentifier 

Optionally points to a variable that receives a numeric identifier associated with the 
port. 

ReplyMessage 

Optionally points to a caller-allocated buffer or variable that specifies the reply mes- 
sage to send to the port. 

Message 

Points to a caller-allocated buffer or variable that receives the message sent to the port. 

Timeout 

Optionally points to a value that specifies the absolute or relative time at which the 
wait is to be timed out. A negative value specifies an interval relative to the current 
time. The value is expressed in units of 100 nanoseconds. Absolute times track any 
changes in the system time; relative times are not affected by system time changes. If 
Timeout is a null pointer, the wait will not timeout. 

Return Value 

Returns STATUS_SUCCESS, STATUS_TIMEOUT or an error status, such as 
STATUS_INVALID_HANDLE or ST ATUS_RE P LY_MESSAG E_M I SMATCH . 

Related Win32 Functions 

None. 

Remarks 

The routine ZwReplyWaitReceivePortEx is only present in Windows 2000. 
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ZwReadRequestData 



ZwReadRequestData reads the data from the process virtual address space referenced by 
a message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReadRequestData ( 

IN HANDLE PortHandle, 

IN PP0RT_MESSAGE Message, 

IN ULONG Index, 

OUT PVOID Buffer, 

IN ULONG BufferLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Message 

Points to a caller-allocated buffer or variable that contains a message received from the 
port. 

Index 

An index into the array of buffer address/length pairs in the Message. 

Buffer 

Points to a caller-allocated buffer or variable that receives data transferred from the vir- 
tual address space of the sender ot the Message. 

BufferLength 

The size in bytes of Buffer. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually transferred if 
the call was successful. If this information is not needed, ReturnLength may be a null 
pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE . 

Related Win32 Functions 

None. 

Remarks 

The sender of the message should have initialized the VirtualRangesOff set member 
of the P0RT_MESSAGE structure and stored valid virtual address range information in the 
data portion of the message. 





1996 Chi 2 12/2/99 9:30 AM Page 271 



Ports (Local Procedure Calls): ZwWriteRequestData 271 



ZwWriteRequestData 



ZwWriteRequestData writes data to the process virtual address space referenced by a 
message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWriteRequestData ( 

IN HANDLE PortHandle, 

IN PP0RT_MESSAGE Message, 

IN ULONG Index, 

IN PVOID Buffer, 

IN ULONG BufferLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Message 

Points to a caller- allocated buffer or variable that contains a message sent to the port. 

Index 

An index into the array of buffer address/length pairs in the Message. 

Buffer 

Points to a caller-allocated buffer or variable that contains data to be transferred to the 
virtual address space of the sender of the Message. 

BufferLength 

The size in bytes of Buff er. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually transferred if 
the call was successful. If this information is not needed, ReturnLength may be a null 
pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE. 

Related Win32 Functions 

None. 

Remarks 

The sender of the message should have initialized the VirtualRangesOff set member 
of the P0RT_MESSAGE structure and have stored valid virtual address range information 
in the data portion of the message. 
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ZwQuerylnformationPort 



ZwQuerylnformationPort retrieves information about a port object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationPort ( 

IN HANDLE PortHandle, 

IN P0RT_INF0RMATI0N_CLASS Portlnf ormationClass, 

OUT PVOID Portlnformation, 

IN ULONG PortlnformationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

PortHandle 

A handle to a port object. The handle must grant GENERIC_READ access. 

Portlnformation Class 

Specifies the type of port object information to be queried. The permitted values are 
drawn from the enumeration P0RT_INF0RMATI0N_CLASS, described in the following 
section. 

Portlnformation 

Points to a caller-allocated buffer or variable that receives the requested port object 
information. 

PortlnformationLength 

Specifies the size in bytes of Portlnformation, which the caller should set according 
to the given Portlnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Portlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE or 
STATUS_I N VAL I D_I N F0_CLASS . 

Related Win32 Functions 

None. 

Remarks 

None. 
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PORT_INFORMATION_CLASS 



typedef enum _P0RT_INF0RMATI0N_CLASS { 
PortBasicInformation 
} P0RT_INF0RMATI0N_CLASS; 



PortBasicInformation 



typedef struct _P0RT_BAS I CONFORMATION { 

} P0RT_BASIC_INF0RMATI0N, *PP0RT_BASIC_INF0RMATI0N ; 



Remarks 

P0RT_BAS I CONFORMATION does not have any members. 



ZwImpersonateClientOfPort 



ZwImpersonateClientOfPort impersonates the security context of the client of a port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwImpersonateClientOfPort ( 

IN HANDLE PortHandle, 

IN PP0RT_MESSAGE Message 

); 



Parameters 

PortHandle 

A handle to a port object. The handle need not grant any specific access. 

Message 

Points to a caller-allocated buffer or variable that contains a message sent by the client 
of the port. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_HANDLE, 
STATUS_INVALID_PORT_HANDLE, or STATUS_PORT_DISCONNECTED. 

Related Win32 Functions 

None. 

Remarks 

None. 
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Example 12.1: Connecting to a Named Port 



#include "ntdll.h" 

#include <stdlib.h> 

#include <stdio.h> 

template <int i> struct P0RT_MESSAGEX : NT: : P0RT_MESSAGE { 

UCHAR Data [ i] ; 

}; 

DWORD WINAPI client (PVOID) 

{ 

NT: :UNICODE_STRING name; 

NT : :RtlInitUnicodeString(&name, L"\\Test") ; 

HANDLE hSection = CreateFileMapping (HANDLE (OxFFFFFFFF) , 0, 

PAGE_READWRITE , 0, 0x50000, 0); 

ULONG n, cd[] = {1, 2, 3, 4, 5}, cdn = sizeof cd; 

NT: : SECURITY_QUALITY_OF_SERVICE sqos 

= {sizeof sqos, NT: :SecurityImpersonation, TRUE, TRUE}; 

NT: :PORT_SECTION_WRITE psw = {sizeof psw, hSection, 0x20000, 0x30000}; 
NT: :PORT_SECTION_READ psr = {sizeof psr}; 

HANDLE hPort ; 

NT: :ZwConnectPort (&hPort , &name, &sqos, &psw, &psr, &n, cd, &cdn); 

PORT_MESSAGEX<40> req, rep; 

CHAR txt [ ] = "Hello, World"; 

memset(&req, 0xaa, sizeof req); 
memset(&rep, 0xcc, sizeof req); 

req .MessageType = NT: : LPC_NEW_MESSAGE; 
req.MessageSize = sizeof req; 
req . VirtualRangesOff set = 0; 
req.DataSize = sizeof txt; 
strcpy(PSTR(req.Data) , txt); 

while (true) { 

NT: :ZwRequestWaitReplyPort (hPort, &req, &rep); 

printf ("client () : type %hd, id %hu\n", 
rep. MessageType, rep.Messageld) ; 

Sleep(1000) ; 

} 

return 0; 

} 

int main() 

{ 

NT: :UNICODE_STRING name; 

NT : :RtlInitUnicodeString(&name, L"\\Test") ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa, 0, &name}; 

PORT_MESSAGEX<40> req; 

HANDLE hPort; 



memset(&req, 0xee, sizeof req); 
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NT: :ZwCreatePort (&hPort , &oa, 0, sizeof req, 0); 

ULONG tid ; 

HANDLE hThread = CreateThread(0, 0, client, 0, 0, &t id ) ; 

NT: :ZwListenPort (hPort , &req); 

ULONG n = 0x9000; 

HANDLE hSection = CreateFileMapping (HANDLE (0XFFFFFFFF) , 0, 

PAGE_READWRITE , 0, n, 0); 

NT: :PORT_SECTION_WRITE psw = {sizeof psw, hSection, 0, n}; 

NT: :PORT_SECTION_READ psr = {sizeof psr}; 

HANDLE hPort2; 

req.DataSize = 4; req.Data[0] = 0xfe; 

NT: :ZwAcceptConnectPort (&hPort2, 0xdeadbabe, &req, TRUE, &psw, &psr); 

NT : :ZwCompleteConnectPort (hPort2) ; 

while (true) { 

ULONG portid; 

NT: :ZwReplyWaitReceivePort (hPort2, &portid, 0, &req); 

printf ( "server( ) : type %hd, id %hu\n", 
req .MessageType, req .Messageld) ; 

req.DataSize = 1; req.Data[0] = 0xfd; 

NT: :ZwReplyPort (hPort2, &req); 

} 

return 0; 

} 

Example 12.1 is intended to be run under the control of a debugger so that the values 
of variables can be examined at each step of the program; it does not do anything use- 
ful and contains extraneous statements (such as the memset statements), which need 
not appear in production code. 

The important steps taken by the function main are as follows: 

1. Create a named port by calling ZwCreatePort. The MaxDataSize parameter is 
checked for consistency but is otherwise unused. Therefore a value of zero can be 
specified. 

2. Listen on the port for connection requests. A connect message includes the con- 
nect data specified by the caller of ZwConnectPort. The connect data and the 
identity of the process making the request can be used to decide whether to 
accept or reject the connection request. 

3. Update the data portion of the connection request message; these changes will be 
visible to the caller of ZwConnectPort upon return from that function. 

4. In anticipation of the need to transfer large amounts of data, create a pagef ile- 
backed section and associate with the port by calling ZwAcceptConnectPort. 

5. Complete the connection by calling ZwCompleteConnectPort. This causes the 
client’s call to ZwConnectPort to return. 
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6. Loop, receiving requests, acting upon the contained data and replying. 

The important steps taken by the function client are as follows: 

1. In anticipation of the need to transfer large amounts of data, create a pagef ile- 
backed section. 

2. Initialize the connect data, and connect to the named port by calling 
ZwConnectPort. This call also associates the section with the port. 

3. Initialize the P0RT_MESSAGE structure that will carry the requests to the server. 
The four fields that must be initialized are MessageType, MessageSize, DataSize, 
and VirtualRangesOff set. 

4. Loop, sending requests and receiving replies. 
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The system services described in this chapter create and manipulate file objects. 



Z wCre ateFile 



ZwCreateFile creates or opens a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateFile( 

OUT PHANDLE FileHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PLARGE_INTEGER AllocationSize OPTIONAL, 
IN ULONG FileAttributes, 

IN ULONG ShareAccess, 

IN ULONG CreateDisposition, 

IN ULONG CreateOptions, 

IN PVOID EaBuffer OPTIONAL, 

IN ULONG EaLength 

); 



Parameters 

FileHandle 

Points to a variable that will receive the file object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the file object. This parameter 
can be zero, or any compatible combination of the following flags: 



LU 
_l 
1— 1 
U_ 


_ANY_ACCESS 


0X0000 


ii 


any type 


FILE_ 


_READ_ACCESS 


0x0001 


n 


file & pipe 


LU 
_i 
i— i 
Li- 


_READ_DATA 


0X0001 


ii 


file & pipe 


LU 
_l 
1— 1 
U_ 


LIST_DIRECTORY 


0X0001 


ii 


directory 


LU 
_l 
1— 1 
U_ 


WRITE_ACCESS 


0x0002 


ii 


file & pipe 


LU 
_l 
1— 1 
U- 


_WRITE_DATA 


0x0002 


ii 


file & pipe 


FILE_ 


_ADD_FILE 


0x0002 


ii 


directory 
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FILE. 


_APPEND_DATA 


0x0004 


// 


file 


FILE. 


_ADD_SUBD I RECTORY 


0x0004 


// 


directory 


FILE 


_CREATE_PIPE_INSTANCE 


0X0004 


ii 


named pipe 


FILE. 


_READ_EA 


0X0008 


ii 


file & directory 


FILE. 


_WRITE_EA 


0X0010 


// 


file & directory 


FILE 


.EXECUTE 


0X0020 


// 


file 


LLI 

1 

t— 1 
Li. 


.TRAVERSE 


0x0020 


ii 


directory 


FILE. 


_DELETE_CHILD 


0X0040 


ii 


directory 


FILE. 


_READ_ATTRIBUTES 


0x0080 


// 


all types 


FILE. 


_WRITE_ATTRIBUTES 


0x0100 


// 


all types 


FILE. 


_ALL_ACCESS 


// All of 


the 


preceding + 



STANDARD_RIGHTS_ALL 



Object Attributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, 
and OBJ_OPENLINK are not valid attributes for a file object. 



loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. On return, the Information member contains create disposition, 
which will be one of the following values: 

FILE_SUPERSEDED 

FILE_OPENED 

FILE_CREATED 

FILE_OVERWRITTEN 

FILE_EXISTS 

FILE_DOES_NOT_EXIST 



AllocationSize 

Optionally specifies the initial allocation size in bytes for the file. A nonzero value has 
no effect unless the file is being created, overwritten, or superseded. 



FileAttributes 

Specifies file attributes to be applied if a new file is created. This parameter can be 
zero, or any compatible combination of the following flags: 

FILE_ATTRIBUTE_READONLY 

FILE_ATTRIBUTE_HIDDEN 

FILE_ATTRIBUTE_SYSTEM 

FI LE_ATTR I BUTE_DI RECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FI LE_ATTR I BUTE_SPARSE_FI LE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_NOT_CONTENT_I NDEXED 

FILE ATTRIBUTE ENCRYPTED 



1996 CHI 3 



12/1/99 



12:34 PM 



Page 




Files: ZwCreateFile 279 



Share Access 

Specifies the limitations on sharing of the file. This parameter can be zero, or any com- 
patible combination of the following flags: 

FILE_SHARE_READ 
FILE_SHARE_WRITE 
F I L E_S H AR E_D E L ET E 



CreateDisposition 

Specifies what to do, depending on whether the file already exists. This must be one of 
the following values: 

FILE_SUPERSEDE 

FILE_0PEN 

FILE_CREATE 

FILE_OPEN_IF 

FILE_OVERWRITE 

FILE_OVERWRITE_IF 



Create Options 

Specifies the options to be applied when creating or opening the file, as a compatible 

combination of the following flags: 

FILE_DIRECTORY_FILE 

FILE_WRITE_THROUGH 

FILE_SEQUENTIAL_ONLY 

FILE_NO_INTERMEDIATE_BUFFERING 

FILE_SYNCHRONOUS_IO_ALERT 

FILE_SYNCHRONOUS_IO_NONALERT 

FILE_NON_DIRECTORY_FILE 

FILE_CREATE_TREE_CONNECTION 

FILE_COMPLETE_IF_OPLOCKED 

F I L E_N0_E A_KN OWL EDGE 

FI LE_0PEN_F0R_REC0VERY 

FILE_RANDOM_ACCESS 

FILE_DELETE_ON_CLOSE 

FILE_OPEN_BY_F I LE_I D 

FILE_OPEN_FOR_BACKUP_INTENT 

FILE_N0_C0MPRESSI0N 

FILE_RESERVE_OPFILTER 

FILE_OPEN_REPARSE_POINT 

FILE_OPEN_NO_RECALL 

FILE_0PEN_F0R FR E E_S PAC E_QU E R Y 



EaBuffer 

Points to a caller-allocated buffer or variable that contains Extended Attributes 
information. 

EaLength 

Specifies the size in bytes of EaBuffer. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_NOT_FOUND, STATUS_OBJECT_NAME_COLLISION, 

ST ATUS_0B J ECT_NAME_I N VAL I D , STATUS_SHARING_VIOLATION, STATUS_NOT_A_D I RECTORY, or 
STATUS FILE IS A DIRECTORY. 
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Related Win32 Functions 

CreateFile. 



Remarks 

ZwCreateFile is documented in the DDK. 

The kernel mode Transport Driver Interface (TDI) uses extended attributes extensive- 
ly, and extended attributes can be stored and retrieved on NTFS files. 

Example 13.1 demonstrates how to use FILE_OPEN_BY_FILE_ID. 



ZwOpenFile 



ZwOpenFile opens a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenFile ( 

OUT PHANDLE FileHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttribUtes , 
OUT PI0_STATUS_BL0CK IoStatUSBIOCk, 

IN ULONG ShareAccess, 

IN ULONG OpenOptions 

); 



Parameters 

FileHandle 

Points to a variable that will receive the file object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the file object. This parameter 
can be zero, or any compatible combination of the following flags: 



FILE. 


_ANY_ACCESS 


0X0000 


ii 


any type 


FILE. 


_READ_ACCESS 


0x0001 


// 


file & pipe 


LLI 

1 

1— 1 
Ll_ 


_READ_DATA 


0X0001 


ii 


file & pipe 


FILE. 


_LIST_DIRECTORY 


0X0001 


it 


directory 


FILE. 


_WRITE_ACCESS 


0X0002 


// 


file & pipe 


FILE. 


_WRITE_DATA 


0X0002 


ii 


file & pipe 


LLI 
_l 
t— 1 
Li. 


_ADD_FILE 


0x0002 


ii 


directory 


FILE. 


_APPEND_DATA 


0X0004 


ii 


file 


FILE. 


_ADD_SUBD I RECTORY 


0X0004 


ii 


directory 


LLI 
_l 
t— 1 
U_ 


_CREATE_PIPE_INSTANCE 


0X0004 


ii 


named pipe 


FILE. 


_READ_EA 


0X0008 


ii 


file & directory 


FILE. 


_WRITE_EA 


0X0010 


// 


file & directory 


FILE. 


.EXECUTE 


0X0020 


ii 


file 


LLI 
_l 
t— 1 
LL. 


.TRAVERSE 


0x0020 


ii 


directory 
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FILE_DELETE_CHILD 


0x0040 


ii 


directory 


FILE_READ_ATTRIBUTES 


0x0080 


// 


all types 


FILE_WRITE_ATTRIBUTES 


0x0100 


ii 


all types 


FILE_ALL_ACCESS 


// All of 


the 


preceding + STANDARD_RIGHTS_ALL 



Object Attributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, 
and 0BJ_0PENLINK are not valid attributes for a file object. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. If the call is successful, the Information member contains create 
disposition, which will be one of the following values: 

FILE_OPENED 

FILE_DOES_NOT_EXIST 



ShareAccess 

Specifies the limitations on sharing of the file. This parameter can be zero, or any com- 
patible combination of the following flags: 

FILE_SHARE_READ 

FILE_SHARE_WRITE 

FILE_SHARE_DELETE 



OpenOptions 

Specifies the options to be applied when opening the file as a compatible combination 

of the following flags: 

FILE_DIRECTORY_FILE 

FILE_WRITE_THROUGH 

FILE_SEQUENTIAL_ONLY 

FILE_NO_INTERMEDIATE_BUFFERING 

FILE_SYNCHRONOUS_IO_ALERT 

FILE_SYNCHRONOUS_IO_NONALERT 

FILE_NON_DIRECTORY_FILE 

FILE_CREATE_TREE_CONNECTION 

FILE_COMPLETE_IF_OPLOCKED 

FILE_NO_EA_KNOWLEDGE 

FI LE_0PEN_F0R_REC0VERY 

FILE_RANDOM_ACCESS 

FILE_DELETE_ON_CLOSE 

FILE_OPEN_BY_FILE_ID 

FILE_OPEN_FOR_BACKUP_INTENT 

FILE_N0_C0MPRESSI0N 

FILE_RESERVE_OPFILTER 

FILE_OPEN_REPARSE_POINT 

FILE_OPEN_NO_RECALL 

FILE_0PEN_F0R FR E E_S PAC E_QU E R Y 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

STATUS_OBJ ECT_NAME_NOT_FOUND, STATUS_OBJ ECT_NAME_I NVAL I D, 

ST ATUS_SHAR I NG_V I OLAT ION, STATUS_NOT_A_DI RECTORY, or STATUS_FILE_IS_A_DIRECTORY. 
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Related Win32 Functions 

None. 



Remarks 

ZwOpenFile(FileHandle, DesiredAccess, ObjectAttributes, IoStatusBlock, 
ShareAccess, OpenOptions) 
is equivalent to: 

ZwCreateFile(FileHandle, DesiredAccess, ObjectAttributes, IoStatusBlock, 0, 0, 
ShareAccess, FILE_0PEN, OpenOptions, 0, 0) 



ZwDeleteFile 



ZwDeleteFile deletes a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeleteFile( 

IN POBJECT_ATTRIBUTES ObjectAttributes 

); 

Parameters 

ObjectAttributes 

Specifies the file to delete. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 

Remarks 

There are alternative methods of deleting a file, and the Win32 DeleteFile function 
uses ZwSetlnformationFile with a FilelnformationClass of 
FileDisposit ion Informat ion. 



ZwFlushBuffersFile 



ZwFlushBuffersFile flushes any cached data to the storage medium or network. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFlushBuffersFile ( 

IN HANDLE FileHandle, 

OUT PI0_STATUS_BL0CK IoStatusBlock 

); 
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Parameters 

FileHandle 

A handle to a file object. The handle need not grant any specific access. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

FlushFileBuff ers. 

Remarks 

If FileHandle refers to a file volume, all of the open files on the volume are flushed. 



ZwCancelloFile 



ZwCancelloFile cancels all pending I/O operations initiated by the current thread on 
the file object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCancelIoFile( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatusBlock 

); 

Parameters 

FileHandle 

A handle to a file object. The handle need not grant any specific access. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS INVALID HANDLE. 
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Related Win32 Functions 

Cancello. 



Remarks 

None. 



ZwReadFile 



ZwReadFile reads data from a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReadFile( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 
IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

OUT PVOID Buffer, 

IN ULONG Length, 

IN PLARGE_INTEGER ByteOffset OPTIONAL, 
IN PULONG Key OPTIONAL 
); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_READ_DATA access. 

Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 



IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. On return, the Information member contains the number of 
bytes actually read. 
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Buffer 

Points to a caller-allocated buffer or variable that receives the data read from the file. 

Length 

Specifies the size in bytes of Buffer and the number of bytes to read from the file. 

Byte Offset 

Optionally points to a variable specifying the starting byte offset within the file at 
which to begin the read operation. 

Key 

Optionally points to a variable that, if its value matches the key specified when the file 
byte range was locked, allows the lock to be ignored. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, STATUS_FILE_LOCK_CONFLICT, or 
ST ATU S_E N D_0 F_F I L E . 

Related Win32 Functions 

ReadFile, ReadFileEx. 

Remarks 

ZwReadFile is documented in the DDK. 



ZwWriteFile 



ZwWriteFile writes data to a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWriteFile( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 
IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PVOID Buffer, 

IN ULONG Length, 

IN PLARGE_INTEGER ByteOffset OPTIONAL, 
IN PULONG Key OPTIONAL 
); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_WRITE_DATA and/or 
FILE APPEND DATA access. 
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Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock , 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. On return, the Information member contains the number of 
bytes actually written. 

Buffer 

Points to a caller- allocated buffer or variable that contains the data to write to the file. 

Length 

Specifies the size in bytes of Buffer and the number of bytes to write to the file. 

Byte Offset 

Optionally points to a variable specifying the starting byte offset within the file at 
which to begin the write operation. 

Key 

Optionally points to a variable that, if its value matches the key specified when the file 
byte range was locked, allows the lock to be ignored. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_FILE_LOCK_CONFLICT. 

Related Win32 Functions 

WriteFile, WriteFileEx. 

Remarks 



ZwWriteFile is documented in the DDK. 
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ZwReadFileScatter 



ZwReadFileScatter reads data from a file and stores it in a number of discontiguous 
buffers. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReadFileScatter ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PFILE_SEGMENT_ELEMENT Buffer, 

IN ULONG Length, 

IN PLARGE_INTEGER ByteOffset OPTIONAL, 

IN PULONG Key OPTIONAL 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_READ_DATA access. 

Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

P 1 0_ST ATUS_B LOCK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. On return, the Information member contains the number of 
bytes actually read. 

Buffer 

Points to a caller- allocated buffer or variable that contains an array of 
FILE_SEGMENT_ELEMENT pointers to buffers. Each buffer should be the size of a system 
memory page and should be aligned on a system memory page size boundary. 

Length 

Specifies the number of bytes to read from the file. 
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Byte Offset 

Optionally points to a variable specifying the starting byte offset within the file at 
which to begin the read operation. 

Key 

Optionally points to a variable that, if its value matches the key specified when the file 
byte range was locked, allows the lock to be ignored. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, STATUS_FILE_LOCK_CONFLICT, or 
ST ATU S_E N D_0 F_F I L E . 

Related Win32 Functions 

ReadFileScatter. 

Remarks 

None. 



ZwWriteFileGather 



ZwWriteFileGather retrieves data from a number of discontiguous buffers and writes it 
to a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwWriteFileGather ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN PFILE_SEGMENT_ELEMENT Buffer, 

IN ULONG Length, 

IN PLARGE_INTEGER ByteOffset OPTIONAL, 

IN PULONG Key OPTIONAL 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_WRITE_DATA and/or 
FILEAPPENDDATA access. 



Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 
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ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock , 

ULONG Reserved); 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. On return, the Information member contains the number of 
bytes actually written. 

Buffer 

Points to a caller- allocated buffer or variable that contains an array of 
FILE_SEGMENT_ELEMENT pointers to buffers. Each buffer should be the size of a system 
memory page and should be aligned on a system memory page size boundary. 

Length 

Specifies the number of bytes to write to the file. 

Byte Offset 

Optionally points to a variable specifying the starting byte offset within the file at 
which to begin the write operation. 

Key 

Optionally points to a variable that, if its value matches the key specified when the file 
byte range was locked, allows the lock to be ignored. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_FILE_LOCK_CONFLICT. 

Related Win32 Functions 

WriteFileGather. 

Remarks 

None. 
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ZwLockFile 



ZwLockFile locks a region of a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwLockFile( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 
IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN PULARGE_INTEGER LockOffset, 

IN PULARGE_INTEGER LockLength, 

IN ULONG Key, 

IN BOOLEAN Faillmmediately , 

IN BOOLEAN ExclusiveLock 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_READ_DATA and/or 
FILE_WRITE_DATA access. 



Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PI0_STATUS_BL0CK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

LockOffset 

Points to a variable that specifies the offset, in bytes, to the byte range to lock. 

LockLength 

Points to a variable that specifies the length, in bytes, of the byte range to lock. 
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Key 

Specifies a value that, if matched by the key specified in a call to ZwReadFile or 
ZwWriteFile, allows the lock to be ignored. Also used to group locks. 

Faillmmediately 

Specifies whether the attempt to lock a byte range should return with an error status 
rather than wait if the lock cannot be acquired immediately. 

ExclusiveLock 

Specifies whether the lock should be exclusive or shared. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_LOCK_NOT_GRANTED. 

Related Win32 Functions 

LockFile, LockFileEx. 

Remarks 

None. 



ZwUnlockFile 



ZwUnlockFile unlocks a locked region of a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwUnlockFile( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN PULARGE_INTEGER LockOffset, 

IN PULARGE_INTEGER LockLength, 

IN ULONG Key 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_READ_DATA and/or 
FILE_WRITE_DATA access. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

LockOffset 

Points to a variable that specifies the offset, in bytes, to the byte range to unlock. 
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LockLength 

Points to a variable that specifies the length, in bytes, of the byte range to unlock. 

Key 

Specifies a value that identifies the lock. This should match the value specified when 
the byte range was locked. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE or STATUS_RANGE_NOT_LOCKED. 

Related Win32 Functions 

UnlockFile, UnlockFileEx. 

Remarks 

None. 



ZwDeviceloControlFile 



ZwDeviceloControlFile performs an I/O control operation on a file object that repre- 
sents a device. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeviceloControlFile ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN ULONG IoControlCode, 

IN PVOID InputBuffer OPTIONAL, 

IN ULONG InputBufferLength, 

OUT PVOID OutputBuffer OPTIONAL, 

IN ULONG OutputBufferLength 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant access compatible with the access field 
of the IoControlCode. 



Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 
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ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock , 

ULONG Reserved); 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

IoControlCode 

Specifies the particular 1/ O control operation to perform. 

InputBuffer 

Optionally points to a caller-allocated buffer or variable that contains data specific to 
the IoControlCode. 

Inp u tBufferLength 

The size, in bytes, of InputBuffer. 

OutputBuffer 

Optionally points to a caller-allocated buffer or variable that receives data specific to 
the IoControlCode. 

Ou tp u tB ufferLength 

The size, in bytes, of OutputBuffer. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_INVALID_DEVICE_REQUEST. 

Related Win32 Functions 

DeviceloControl. 

Remarks 

None. 
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ZwFsControlFile 



ZwFsControlFile performs a file system control operation on a file object that repre- 
sents a file-structured device. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFsControlFile( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN ULONG FsControlCode, 

IN PVOID InputBuffer OPTIONAL, 

IN ULONG InputBufferLength, 

OUT PVOID OutputBuffer OPTIONAL, 

IN ULONG OutputBufferLength 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant access compatible with the access field 
of the FsControlCode. 



Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

FsControlCode 

Specifies the particular file system control operation to perform. 

InputBuffer 

Optionally points to a caller-allocated buffer or variable that contains data specific to 
the FsControlCode. 
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InputBufferLength 

The size, in bytes, of InputBuffer. 

OutputBuffer 

Optionally points to a caller-allocated buffer or variable that receives data specific to 
the FsControlCode. 

Ou tpu tBufferLength 

The size, in bytes, of OutputBuffer. 

Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_INVALID_DEVICE_REQUEST. 

Related Win32 Functions 

DeviceloControl. 

Remarks 

The control codes and data structures for many interesting file system control opera- 
tions are defined in winioctl.h. 



ZwNotifyChangeDirectoryFile 



ZwNotifyChangeDirectoryFile monitors a directory for changes. 

ZwNotifyChangeDirectoryFile ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

OUT PFILE_NOTIFY_INFORMATION Buffer, 

IN ULONG BufferLength, 

IN ULONG NotifyFilter, 

IN BOOLEAN WatchSubtree 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_LIST_DIRECTORY access. 

Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 
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ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PIO_STATUS_BLOCK IoStatusBlock, 

ULONG Reserved); 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 



IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Buffer 

Points to a caller- allocated buffer or variable that receives data describing the changes 
detected. The data is a sequence of FILE_NOTIFY_INFORMATION structures. 



BufferLength 

The size, in bytes, of Buffer. 



Notify Filter 

Specifies the types of changes to be monitored. This parameter can be any combina- 
tion of the following flags: 

FI LE_N0TI FY_CHANGE_F I LE_NAME 
FILE_NOTIFY_CHANGE_D I R_NAME 
FILE_NOTIFY_CHANGE_ATTRIBUTES 
FILE_NOTIFY_CHANGE_SIZE 
F I LE_N0T I FY_CHANGE_LAST_WR I TE 
F I L E_N0T I FY_CHANGE_LAST_ACCESS 
F I L E_N0T I F Y_CH ANG E_CR E AT ION 
FILE_NOTIFY_CHANGE_EA 
FILE_NOTIFY_CHANGE_SECURITY 
F I L E_N0T I F Y_CH ANG E_STR EAM_NAME 
F I L E_N OT I F Y_C H ANG E_STR E AM_S I Z E 
FILE_NOTIFY CHANG E_STR EAM_WR I TE 



WatchSubtree 

Specifies whether changes to all the directories in the subtree below FileHandle should 
also be monitored. 



Return Value 

Returns STATUS_SUCCESS, STATUS_PENDING or an error status, such as 
STATUS ACCESS DENIED or STATUS INVALID HANDLE. 
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Related Win32 Functions 

ReadDirectoryChangesW, FindFirstChangeNotif ication, FindNextChangeNotif ication. 



Remarks 

Although more FI LTER_NOTI FY_XXX flags are defined than are listed in the Win32 docu- 
mentation for ReadDirectoryChangesW, the supported file systems do not implement 
the corresponding functionality. 



FILE_N OTIF Y_INFORMATION 



typedef struct _FILE_NOTIFY_INFORMATION { 

ULONG NextEntryOff set ; 

ULONG Action; 

ULONG NameLength; 

ULONG Name[1 ] ; 

} FILE_NOTIFY_INFORMATION, *PFILE_NOTIFY_INFORMATION ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next record. A value of zero 
indicates that this is the last record. 



Action 

The type of change that occurred. Possible values are: 

FILE_ACTION_ADDED 
FILE_ACTION_REMOVED 
FILE_ACTION_MODIFIED 
F I L E_ACT 1 0 N_R E N AM E D_0 L D_N AM E 
F I L E_ACT 1 0 N_R E N AM E D_N EW_N AM E 
FILE_ACTION_ADDED_STREAM 
F I L E_ACT 1 0 N_R E MO V E D_ST R E AM 
F I L E_ACT I0N_M0DIFIE D_STR E AM 



NameLength 

Specifies the size, in bytes, of Name. 

Name 

Contains the name of the file or stream that changed. 

Remarks 

None. 
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ZwQueryEaFile 



ZwQueryEaFile retrieves information about the extended attributes of a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryEaFile( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

OUT PFILE_FULL_EA_INFORMATION Buffer, 

IN ULONG BufferLength, 

IN BOOLEAN ReturnSingleEntry , 

IN PFILE_GET_EA_INFORMATION EaList OPTIONAL, 

IN ULONG EaListLength, 

IN PULONG Ealndex OPTIONAL, 

IN BOOLEAN RestartScan 

); 



Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_READ_EA access. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Buffer 

Points to a caller-allocated buffer or variable that receives the extended attributes. The 
data is a sequence of FILE_FULL_EA_INFORMATION structures. 

BufferLength 

The size, in bytes, of Buffer. 

ReturnSingleEntry 

Specifies whether a single entry should be returned. If false, as many entries as will fit 
in the buffer are returned. 

EaList 

Optionally points to a caller-allocated buffer or variable that contains a sequence of 
F I LE_GET_EA_IN FORMATION structures specifying the names of the extended attributes to 
query. 

EaListLength 

The size, in bytes, of EaList. 

Ealndex 

Optionally points to a variable that specifies the index of the extended attribute to 
query. 

RestartScan 

Specifies whether the scan of the extended attributes should be restarted. 
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Return Value 

Returns STATUS_SUCCESS, STATUS_NO_MORE_ENTRIES or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID_HANDLE, or STATUS_EA_LIST_INCONSISTENT. 

Related Win32 Functions 

None. 

Remarks 

NTFS supports extended attributes. 



ZwSetEaFile 



ZwSetEaFile sets the extended attributes of a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetEaFile( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PFILE_FULL_EA_INFORMATION Buffer, 

IN ULONG BufferLength 

); 

Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_WRITE_EA access. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Buffer 

Points to a caller-allocated buffer or variable that specifies the extended attributes. The 
data is a sequence of F I LE_FULL_EA_IN FORMAT ION structures. 

BufferLength 

The size, in bytes, oi Buffer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, ST ATUS_I N VAL I D_E A_NAM E , or STATUS_INVALID_EA_FLAG. 

Related Win32 Functions 

None. 

Remarks 

None. 
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FILE_FULL_EA_INFORMATION 



typedef struct _FILE_FULL_EA_INFORMATION { 

ULONG NextEntryOff set ; 

UCHAR Flags; 

UCHAR EaNameLength; 

USHORT EaValueLength; 

CHAR EaName [1 ] ; 

// UCHAR EaData[]; // Variable length data not declared} 

FILE_FULL_EA_INFORMATION, 

*PFILE_FULL_EA_INFORMATION; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

Flags 

A bit array of flags qualifying the extended attribute. 

EaNameLength 

The size in bytes of the extended attribute name. 

Ea ValueLength 

The size in bytes of the extended attribute value. 

EaName 

The extended attribute name. 

EaData 

The extended attribute data. The data follows the variable length EaName and is located 
by adding EaNameLength + 1 to the address of the EaName member. 



Remarks 

FILE_FULL_EA_INFORMATION is documented in the DDK. 



FILE_GET_EA_INFORMATION 



typedef struct _FILE_GET_EA_INF0RMATI0N { 

ULONG NextEntryOff set ; 

UCHAR EaNameLength; 

CHAR EaName [1 ] ; 

} FILE_GET_EA_INF0RMATI0N, *PFILE_GET_EA_INF0RMATI0N ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 
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EaNameLength 

The size in bytes of the extended attribute name. 

EaName 

The extended attribute name. 



Remarks 

None. 



ZwCreateNamedPipeFile 



ZwCreateNamedPipeFile creates a named pipe. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateNamedPipeFile ( 

OUT PHANDLE FileHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 
OUT PI0_STATUS_BL0CK IoStatUSBIOCk , 

IN ULONG ShareAccess, 

IN ULONG CreateDisposition, 

IN ULONG CreateOptions, 

IN BOOLEAN TypeMessage, 

IN BOOLEAN ReadmodeMessage , 

IN BOOLEAN Nonblocking, 

IN ULONG Maxlnstances, 

IN ULONG InBufferSize, 

IN ULONG OutBufferSize, 

IN PLARGE_INTEGER Def aultTimeout OPTIONAL 

); 



Parameters 

FileHandle 

Points to a variable that will receive the file object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the file object. This parameter 



can be zero, or any compatible combination of the 


following flag; 


FILE_ANY_ACCESS 


0X0000 


// 


any type 


FILE_READ_ACCESS 


0X0001 


// 


file & pipe 


F I L E_R E AD_DAT A 


0x0001 


ii 


file & pipe 


FILE_WRITE_ACCESS 


0x0002 


// 


file & pipe 


FILE_WRITE_DATA 


0x0002 


ii 


file & pipe 


FILE_CREATE_PIPE_INSTANCE 


0X0004 


ii 


named pipe 


FILE_READ_ATTRIBUTES 


0x0080 


n 


all types 


FILE_WRITE_ATTRIBUTES 


0x0100 


ii 


all types 


FILE_ALL_ACCESS 


// All of 


the 


preceding + 



STANDARD RIGHTS ALL 
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Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_PERMANENT, 0BJ_EXCLUSIVE, 
and 0BJ_0PENLINK are not valid attributes for a file object. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Share Access 

Specifies the limitations on sharing of the file. This parameter can be zero, or any com- 
patible combination of the following flags: 

FILE_SHARE_READ 

FILE_SHARE_WRITE 

CreateDisposition 

Specifies what to do, depending on whether the file already exists. This must be one of 
the following values: 

FILE_0PEN 

FILE_CREATE 

FILE_0PEN_IF 

Create Options 

Specifies the options to be applied when creating or opening the file, as a compatible 
combination of the following flags: 

FILE_WRITE_THROUGH 

FILE_SYNCHR0N0US_I0_ALERT 

FILE_SYNCHR0N0US_I0_N0NALERT 

TypeMessage 

Specifies whether the data written to the pipe is interpreted as a sequence of messages 
or as a stream of bytes. 

ReadmodeMessage 

Specifies whether the data read from the pipe is interpreted as a sequence of messages 
or as a stream of bytes. 

Nonblocking 

Specifies whether non-blocking mode is enabled. 

Maxlnstances 

Specifies the maximum number of instances that can be created for this pipe. 

InBufferSize 

Specifies the number of bytes to reserve for the input buffer. This value is advisory 
only. 

OutBufferSize 

Specifies the number of bytes to reserve for the output buffer. This value is advisory 
only. 
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DefaultTimeout 

Optionally points to a variable that specifies the default timeout value in units of 100- 
nanoseconds. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 



Related Win32 Functions 

CreateNamedPipe. 



Remarks 

None. 



ZwCreateMailsIotFile 



ZwCreateMailsIotFile creates a mailslot. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateMailsIotFile ( 

OUT PHANDLE FileHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 
OUT PI0_STATUS_BL0CK IoStatUSBIOCk, 

IN ULONG CreateOptions, 

IN ULONG InBufferSize, 

IN ULONG MaxMessageSize, 

IN PLARGE_INTEGER ReadTimeout OPTIONAL 

); 



Parameters 

FileHandle 

Points to a variable that will receive the file object handle if the call is successful. 

DesiredAccess 

Specifies the type of access that the caller requires to the file object. This parameter 



can be zero, or any compatible combination of the 


following flag; 


FILE_ANY_ACCESS 


0x0000 


ii 


any type 


FILE_READ_ACCESS 


0x0001 


ii 


file & pipe 


F I L E_R E AD_DAT A 


0x0001 


ii 


file & pipe 


FILE_WRITE_ACCESS 


0x0002 


ii 


file & pipe 


FILE_WRITE_DATA 


0x0002 


// 


file & pipe 


FILE_READ_ATTRIBUTES 


0x0080 


// 


all types 


FILE_WRITE_ATTRIBUTES 


0x0100 


ii 


all types 


FILE_ALL_ACCESS 


// All of 


the 


preceding + 



STANDARD RIGHTS ALL 
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Object Attributes 

Points to a structure that specifies the objects attributes. 0BJ_PERMANENT, 0BJ_EXCLUSIVE, 
and 0BJ_0PENLINK are not valid attributes for a file object. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Create Options 

Specifies the options to be applied when creating or opening the file, as a compatible 
combination of the following flags: 

FILE_SYNCHR0N0US_I0_ALERT 

FILE_SYNCHR0N0US_I0_N0NALERT 

InBufferSize 

Specifies the number of bytes to reserve for the input buffer. This value is advisory 
only 

MaxMessageSize 

Specifies the maximum size, in bytes, of a single message that can be written to the 
mailslot. 

ReadTimeout 

Optionally points to a variable that specifies the read timeout value in units of 100- 
nanoseconds. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

CreateMailslot. 

Remarks 

None. 



ZwQueryVolumelnformationFile 



ZwQueryVolumelnformationFile retrieves information about a file system volume. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryVolumelnformationFile ( 

IN HANDLE FileHandle, 

OUT PI0_STATUS_BL0CK loStatusBlock, 

OUT PVOID Volumelnformation, 

IN ULONG VolumelnformationLength, 

IN FS_INF0RIVIATI0N_CLASS Volumelnf ormationClass 

); 
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Parameters 

FileHandle 

A handle to a file object representing a volume. The handle must grant FILE_READ_DATA 
access for most information classes. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Volumelnformation 

Points to a caller- allocated buffer or variable that receives the requested volume 
information. 

VolumelnformationLength 

The size in bytes of Volumelnformation, which the caller should set according to the 
given VolumelnformationClass. 

VolumelnformationClass 

Specifies the type of volume information to be queried. The permitted values are a 
subset of the enumeration FS_INF0RMATI0N_CLASS, described in the following section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

GetVolumelnformation, GetDiskFreeSpace, GetDiskFreeSpaceEx, GetDriveType. 

Remarks 

None. 



ZwSetVolumelnformationFile 



ZwSetVolumelnformationFile sets information affecting a file system volume. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetVolumelnformationFile ( 

IN HANDLE FileHandle, 

OUT PI0_STATUS_BL0CK loStatusBlock, 

IN PVOID Buffer, 

IN ULONG BufferLength, 

IN FS_INF0RMATI0N_CLASS VolumelnformationClass 

); 
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Parameters 

FileHandle 

A handle to a file object representing a volume. The handle must grant 
FILE_WRITE_DATA access. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Volumelnformation 

Points to a caller- allocated buffer or variable that contains the volume information to 
be set. 

VolumelnformationLength 

Specifies the size in bytes of Volumelnformation, which the caller should set according 
to the given VolumelnformationClass. 

VolumelnformationClass 

Specifies the type of volume information to be set. The permitted values are a subset 
of the enumeration FS_INF0RMATI0N_CLASS, described in the following section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

SetVolumeLabel. 

Remarks 

None. 



FS_INFORMATION_CLASS 



Query Set 

typedef enum _FSINF0CLASS { 



FileFsVolumelnformation = 1 , 


a 


1 


Y 


N 


FileFsLabellnformation, 


a 


2 


N 


Y 


FileFsSizelnf ormation , 


a 


3 


Y 


N 


FileFsDevicelnformation, 


a 


4 


Y 


N 


FileFsAttributelnf ormation , 


a 


5 


Y 


N 


FileFsControlInf ormation , 


a 


6 


Y 


Y 


FileFsFullSizelnf ormation , 


n 


7 


Y 


N 


FileFsObj ect Id Inf ormation 


a 


8 


Y 


Y 



} FS_INF0RMATI0N_CLASS, *PFS_INF0RMATI0N_CLASS; 





1996 CHI 3 



12/1/99 



12:34 PM 



Page 




Files: FileFsLabel Information 307 



FileFsVolumelnformation 



typedef Struct _FILE_FS_V0LUME_INF0RMATI0N { 

LARGE_INTEGER VolumeCreationTime ; 

ULONG VolumeSerialNumber; 

ULONG VolumeLabelLength; 

UCHAR Unknown; 

WCHAR VolumeLabel[ 1 ] ; 

} FILE_FS_VOLUME_INFORMATION, *PFILE_FS_VOLUME_INFORMATION ; 

Members 

VolumeCreation Time 

The time when the volume was formatted in the standard time format (that is, the 
number of 100-nanosecond intervals since January 1, 1601). 

VolumeSerialNumber 

The volume serial number. 

VolumeLabelLength 

The size, in bytes, of the volume label. 

Unknown 

Interpretation unknown. 

VolumeLabel 

The volume label. 



Remarks 

None. 



FileFsLabellnformation 



typedef Struct _FILE_FS_LABEL_INFORMATION { 

ULONG VolumeLabelLength; 

WCHAR VolumeLabel; 

} FILE_FS_LABEL_INFORMATION, *PFILE_FS_LABEL_INFORMATION ; 

Members 



VolumeLabelLength 

The size, in bytes, of the volume label. 



VolumeLabel 

The volume label. 



Remarks 

None. 
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FileFsSizelnformation 



typedef struct _FILE_FS_SIZE_INF0RMATI0N { 

LARGE_INTEGER TotalAllocationUnits ; 

LARGE_INTEGER AvailableAllocationUnits ; 

ULONG SectorsPerAllocationUnit ; 

ULONG BytesPerSector; 

} FILE_FS_SIZE_INFORMATION , *PFILE_FS_SIZE_INFORMATION; 

Members 

TotalAllocationUnits 

The total number of allocation units on the volume. 

AvailableAllocation Units 

The number of free allocation units on the volume. 

SectorsPerAllocationUnit 

The number of sectors per allocation unit. 

BytesPerSector 

The number of bytes per sector. 



Remarks 

None. 



FileFsDevicelnformation 



typedef struct _FILE_FS_DEVICE_INFORMATION { 

DEVICE_TYPE DeviceType; 

ULONG Characteristics; 

} FILE_FS_DEVICE_INFORMATION, *PFILE_FS_DEVICE_INFORMATION ; 

Members 



DeviceType 

The type of device on which the volume is stored. Possible values include: 

FILE_DEVICE_CD_ROM 
FILE_DEVICE_DFS 
FILE_DEVICE_DISK 
FILE_DEVICE_NETWORK_FILE_SYSTEM 
FILE_DEVICE_VIRTUAL DISK 



Characteristics 

A bit array of flags describing characteristics of the volume. The defined characteristics 
include: 



FILE_REMOVABLE_MEDIA 
FILE_READ_ONLY_DEVICE 
FILE_FLOPPY_DISKETTE 
FILE_WRITE_ONCE_MEDIA 
FILE REMOTE DEVICE 
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FILE_DEVICE_IS_MOUNTED 

FILE_VIRTUAL_VOLUME 

F I L E_AUT0G E N E R AT E D_D E V I C E_N AM E 



Remarks 

FILE FS_DEVICE_I NFORMATION is documented in the DDK. 



FileFsAttributelnformation 



typedef struct _F I LE_FS_ATTR I BUTE_I NFORMATION { 

ULONG FileSystemFlags; 

ULONG MaximumComponentNameLength ; 

ULONG FileSystemNameLength; 

WCHAR FileSystemName[ 1 ] ; 

} FILE_FS_ATTRIBUTE_INFORMATION, *PFILE_FS_ATTRIBUTE_INFORMATION; 



Members 



FileSystemFlags 

A bit array of flags describing properties of the file system. The defined properties 
include: 



FILE_CASE_SENSITIVE_SEARCH 
FI LE_CASE_PRESERVED_NAMES 
FILE_UNIC0DE_0N_DISK 
FILE_PERSISTENT_ACLS 
FILE_FILE_C0MPRESSI0N 
FI LE_V0LUME_QU0TAS 
FI LE_SUPPORTS_SPARSE_FI LES 
FILE_SUPPORTS_REPARSE_POINTS 
FILE_SUPP0RTS_REM0TE_ST0RAGE 
FI LE_V0LUME_IS_C0MPRESSED 
FILE_SUPP0RTS_0BJ ECT_I DS 
FILE_SUPPORTS_ENCRYPTION 
FILE_NAMED STREAMS 



Maximum ComponentNameLength 

The maximum number of characters in a component of a filename. 



FileSystemNameLength 

The size, in bytes, of the file system name. 



FileSystemName 

The file system name. 

Remarks 

None. 
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FileFsControlInformation 



typedef Struct _FILE_FS_C0NTR0L_INF0RMATI0N { 

LARGE_INTEGER Reserved[3]; 

LARGE_INTEGER Def aultQuotaThreshold ; 

LARGE_INTEGER Def aultQuotaLimit ; 

ULONG QuotaFlags; 

} FILE_FS_C0NTR0L_INF0RMATI0N, *PFILE_FS_C0NTR0L_INF0RMATI0N ; 

Members 

Default QuotaThreshold 

The default number of bytes of disk space that may be used by a SID before a warning 
is issued. 

DefaultQuotaLimit 

The default number of bytes of disk space that may be used by a SID. 

QuotaFlags 

An array of flags indicating whether disk quotas are enabled on the volume and the 
actions to take when warning levels and quotas are exceeded. 



Remarks 

This information class can only be used in Windows 2000. 



FileFsFullSizelnformation 



typedef struct _FILE_FS_FULL_SIZE_INFORMATION { 

LARGE_INTEGER TotalQuotaAllocationllnits ; 

LARGE_INTEGER AvailableQuotaAllocationUnits ; 

LARGE_INTEGER AvailableAllocationllnits ; 

ULONG SectorsPerAllocationUnit ; 

ULONG BytesPerSector; 

} FILE_FS_FULL_SIZE_INFORMATION, *PFILE_FS_FULL_SIZE_INFORMATION; 

Members 

Total QuotaAllocationUnits 

The largest number of allocation units on the volume that could be owned by the 
TokenOwner of the primary token of the current process. If volume quotas are enabled, 
this is the smaller of the total number of allocation units on the volume and the vol- 
ume quota for the TokenOwner of the primary token of the current process. 

AvailableQuotaAllocationUnits 

The number of free allocation units on the volume that could be acquired by the 
TokenOwner of the primary token of the current process. If volume quotas are enabled, 
this is the smaller of the total number of free allocation units on the volume and the 
unused volume quota for the TokenOwner of the primary token of the current process. 
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AvailableAllocation Units 

The number of free allocation units on the volume. 

Secto rsPerA llo cation Un i t 

The number of sectors per allocation unit. 

By tesPer Sector 

The number of bytes per sector. 

Remarks 

This information class can only be used in Windows 2000. 



FileFsObjectldlnformation 



typedef struct _FILE_FS_0BJECT_ID_INF0RMATI0N { 

UUID VolumeObjectld; 

ULONG Volume0bjectIdExtendedInfo[12] ; 

} F I LE_FS_0BJ ECT_I D_I N FORMAT ION , * PF I LE_FS_0B J ECT_I D_I N FORMAT I ON ; 

Members 

VolumeObjectld 

The UUID of the volume. 

VolumeObjectldExtendedlnfo 

Interpretation unknown. 



Remarks 

This information class can only be used in Windows 2000. 



ZwQueryQuotalnformationFile 



ZwQueryQuotalnformationFile retrieves information about the disk quotas on a 
volume. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryQuotalnformationFile ( 

IN HANDLE FileHandle, 

OUT PI0_STATUS_BL0CK IoStatUSBIOCk , 

OUT PFILE_USER_QU0TA_INF0RMATI0N Buffer, 

IN ULONG BufferLength, 

IN BOOLEAN ReturnSingleEntry , 

IN PFILE_QU0TA_LIST_INF0RMATI0N QuotaList OPTIONAL, 

IN ULONG QuotaListLength, 

IN PSID ResumeSid OPTIONAL, 

IN BOOLEAN RestartScan 

); 
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Parameters 

FileHandle 

A handle to a file object representing a volume. The handle must grant FILE_READ_DATA 
access. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Buffer 

Points to a caller- allocated buffer or variable that receives the quota information. The 
data is a sequence of FILE_USER_QUOTA_INFORMATION structures. 

BufferLength 

The size, in bytes, of Buffer. 

Return SingleEntry 

Specifies whether a single entry should be returned; if false, as many entries as will fit 
in the buffer are returned. 

QuotaList 

Optionally points to a caller-allocated buffer or variable that contains a sequence of 
FILE_QUOTA_LIST_INFORMATION structures specifying the SIDs to query. 

Quo taLis t Length 

The size, in bytes, of QuotaList. 

ResumeSid 

Optionally points to a variable which specifies the position from which the scan of 
volume disk quotas should be resumed. 

RestartScan 

Specifies whether the scan of the volume disk quotas should be restarted. 

Return Value 

Returns STATUS_SUCCESS, STATUS_NO_MORE_ENTRIES or an error status, such as 
STATUS_ACCESS_DENIED, STATUS_INVALID__HANDLE, or STATUS_QUOTA_LIST_INCONSISTENT. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwQueryQuotalnformationFile is only present in Windows 2000. 

NTFS supports disk quotas. 
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ZwSetQuotalnformationFile 



ZwSetQuotalnformationFile sets disk quota restrictions on a volume. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetQuotalnformationFile! 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PFILE_USER_QUOTA_INFORMATION Buffer, 

IN ULONG BufferLength 

); 

Parameters 

FileHandle 

A handle to a file object representing a volume. The handle must grant 
FILE_WRITE_DATA access. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Buffer 

Points to a caller-allocated buffer or variable that specifies the extended attributes. The 
data is a sequence of FILE_USER_QUOTA_INFORMATION structures. 

BufferLength 

The size, in bytes, of Buffer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, or STATUS_QUOTA_LIST_INCONSISTENT. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwSetQuotalnformationFile is only present in Windows 2000. 

NTFS supports disk quotas. 



I ILF USER QUOTAINFORMATION 



typedef struct _FILE_USER_QU0TA_INF0RMATI0N { 

ULONG NextEntryOff set ; 

ULONG SidLength; 

LARGE_INTEGER ChangeTime; 

LARGE_INTEGER QuotaUsed; 

LARGE_INTEGER QuotaThreshold ; 

LARGE_INTEGER QuotaLimit; 

SID Sid [ 1 ] ; 

} FILE_USER_QU0TA_INF0RMATI0N, *PFILE_USER_QU0TA_INF0RMATI0N ; 
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Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

SidLength 

The size in bytes of Sid. 

ChangeTime 

The time when the quota was last changed in the standard time format (that is, the 
number of 100-nanosecond intervals since January 1, 1601). 

QuotaUsed 

The number of bytes of disk space used by files owned by Sid. 

QuotaThreshold 

The number of bytes of disk space that Sid may use before a warning is issued. 

QuotaLimit 

The number of bytes of disk space that Sid may use. 



Sid 

A SID that identifies a potential owner of files on a volume. 

Remarks 

None. 



FILE_QU OTA_LIST_INFORM ATION 



typedef Struct _FILE_QU0TA_LIST_INF0RMATI0N { 

ULONG NextEntryOff set ; 

ULONG SidLength; 

SID Sid [ 1 ] ; 

} FILE_QU0TA_LIST_INF0RMATI0N, *PFILE_QU0TA_LIST_INF0RMATI0N ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 



SidLength 

The size in bytes of Sid. 



Sid 

A SID that identifies a potential owner of files on a volume. 

Remarks 

None. 
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ZwQueryAttributesFile 



ZwQueryAttributesFile retrieves basic information about a file object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryAttributesFile ( 

IN POBJECT_ATTRIBUTES Ob j ectAttributes , 

OUT PFILE_BASIC_INFORMATION Filelnf ormation 

); 



Parameters 

Obj ectAttributes 

Specifies the file whose attributes are to be queried. 

Filelnf ormation 

Points to a caller- allocated buffer or variable that receives the file attributes. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

GetFileAttributes. 

Remarks 

None. 



ZwQueryFullAttributesFile 



ZwQueryFullAttributesFile retrieves extended information about a file object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryFullAttributesFile ( 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

OUT PFILE_NETWORK_OPEN_INFORMATION Filelnf ormation 

); 



Parameters 

Obj ectAttributes 

Specifies the file whose attributes are to be queried. 

Filelnformation 

Points to a caller-allocated buffer or variable that receives the file attributes. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_OBJ ECT_NAME_NOT_FOUND. 

Related Win32 Functions 

GetFileAttributesEx. 

Remarks 

None. 



ZwQuerylnformationFile 



ZwQuerylnformationFile retrieves information about a file object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnformationFile ( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

OUT PVOID Filelnformation, 

IN ULONG FilelnformationLength, 

IN FILE_INFORMATION_CLASS Filelnf ormationClass 

); 

Parameters 

FileHandle 

A handle to a file object. The handle must grant F I L E_R E AD_D AT A or FILE_READ_EA 
access for some information classes. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Filelnformation 

Points to a caller- allocated buffer or variable that receives the requested file 
information. 

FilelnformationLength 

The size in bytes of Filelnformation, which the caller should set according to the 
given FilelnformationClass. 

FilelnformationClass 

Specifies the type of file information to be queried. The permitted values are a subset 
of the enumeration FILE_INFORMATION_CLASS, described in the following section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 
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Related Win32 Functions 

GetFilelnf ormationByHandle, GetFileSize, GetCompressedFileSize, GetFileTime. 

Remarks 

ZwQuerylnformationFile is documented in the DDK. 



ZwSetlnformationFile 



ZwSetlnformationFile sets information affecting a file object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationFile ( 

IN HANDLE FileHandle, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

IN PVOID Filelnformation, 

IN ULONG FilelnformationLength, 

IN FILE_INFORMATION_CLASS Filelnf ormationClass 

); 

Parameters 

FileHandle 

A handle to a file object. The handle must grant FILE_WRITE_DATA, FILE_WRITE_EA, 
FILE_WRITE_ATTRIBUTES, or DELETE access for some information classes. 

loStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Filelnformation 

Points to a caller- allocated buffer or variable that contains the file information to 
be set. 

FilelnformationLength 

The size in bytes of Filelnformation, which the caller should set according to the 
given FilelnformationClass. 

Filelnformation Class 

Specifies the type of file information to be set. The permitted values are a subset of the 
enumeration FILE_INFORMATION_CLASS, described in the following section. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or STATUS_INFO_LENGTH_MISMATCH. 

Related Win32 Functions 

SetFileAttributes, SetEndOf File, SetFilePointer, SetFileTime, DeleteFile. 
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Remarks 

ZwSetlnformationFile is documented in the DDK. 



ZwQueryDirectoryFile 



ZwQueryDirectoryFile retrieves information about the contents of a directory. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryDirectoryFile ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

OUT PVOID Filelnformation, 

IN ULONG FilelnformationLength, 

IN FILE_INFORMATION_CLASS FilelnformationClass, 

IN BOOLEAN ReturnSingleEntry , 

IN PUNICODE_STRING FileName OPTIONAL, 

IN BOOLEAN RestartScan 

); 



Parameters 

FileHandle 

A handle to a file object representing a directory. The handle must grant 
FILE_LIST_DIRECTORY access. 

Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

P 1 0_ST ATUS_B LOCK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Filelnformation 

Points to a caller- allocated buffer or variable that receives the requested file 
information. 
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FilelnformationLength 

The size in bytes of Filelnf ormation, which the caller should set according to the 
given FilelnformationClass. 

Filelnformation Class 

Specifies the type of file information to be queried. The permitted values are a subset 
of the enumeration FILE_INFORMATION_CLASS, described in the following section. 

Return SingleEntry 

Specifies whether a single entry should be returned. If false, as many entries as will fit 
in the Filelnformation buffer are returned. 

FileName 

Optionally specifies a filename pattern possibly containing and “?” wildcards which 
is used to filter the files in the directory. 

RestartScan 

Specifies whether the scan of the directory should be restarted, or should be resumed 
from the current directory file pointer position. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

ST ATUS_INVALID HANDLE, STATUS_INVALID_INFO_CLASS, STATUS_INFO_LENGTH MISMATCH, 
STATUS_NO_SUCH_FILE, or STATUS_NO_MORE_FILES. 

Related Win32 Functions 

FindFirstFile, FindFirstFileEx, FindNextFile. 

Remarks 

None. 



ZwQueryOleDirectoryFile 



The operation specified by ZwQueryOleDirectoryFile is not implemented by any of the 
supported file systems. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryOleDirectoryFile ( 

IN HANDLE FileHandle, 

IN HANDLE Event OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk , 

OUT PVOID Buffer, 

IN ULONG BufferLength, 

IN FILE_INFORMATION_CLASS Filelnf ormationClass, 

IN BOOLEAN ReturnSingleEntry , 

IN PUNICODE_STRING FileName, 

IN BOOLEAN RestartScan 

); 
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Parameters 

FileHandle 

A handle to a file object representing a directory. The handle must grant 
FILE_LIST_DIRECTORY access. 

Event 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PI0_STATUS_BL0CK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a variable that receives the final completion status and information about the 
requested operation. 

Filelnformation 

Points to a caller-allocated buffer or variable that receives the requested file 
information. 

FilelnformationLength 

The size in bytes of Filelnformation, which the caller should set according to the 
given FilelnformationClass. 

Filelnformation Class 

Specifies the type of file information to be queried. The permitted values are a subset 
of the enumeration FILE_INF0RMATI0N_CLASS, described in the following section. 

Return SingleEntry 

Specifies whether a single entry should be returned. If false, as many entries as will fit 
in the Filelnformation buffer are returned. 

FileName 

Optionally specifies a filename pattern possibly containing “*” and “?” wildcards, 
which is used to filter the files in the directory. 

RestartScan 

Specifies whether the scan of the directory should be restarted, or should be resumed 
from the current directory file pointer position. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

ST ATUS_INVALID HANDLE, STATUS_INVALID_INFO_CLASS, STATUS_INFO_LENGTH MISMATCH, 
STATUS_NO_SUCH_FILE, or STATUS_NO_MORE_FILES. 

Related Win32 Functions 

None. 

Remarks 

ZwQueryOleDirectoryFile is only present in Windows NT 4.0. 

The query OLE directory function is not implemented by the FAT or NTFS file 
systems. 



FILE_INFORMATION_CLASS 



Query Set File/Directory 

typedef enum _FILE_INF0RMATI0N_CLASS { 
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} FILE_INF0RMATI0N_CLASS, *PFILE_INF0RMATI0N_CLASS; 
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FileDirectorylnformation 



typedef struct _FILE_DIRECTORY_INFORMATION { // Information Class 1 
ULONG NextEntryOff set ; 

ULONG Unknown; 

LARGE_INTEGER CreationTime ; 

LARGE_INTEGER LastAccessTime; 

LARGE_INTEGER LastWriteTime; 

LARGE_INTEGER ChangeTime; 

LARGE_INTEGER EndOfFile; 

LARGE_INTEGER AllocationSize; 

ULONG FileAttributes; 

ULONG FileNameLength; 

WCHAR FileName[ 1 ] ; 

} FILE_DIRECTORY_INFORMATION, *PFILE_DIRECTORY_INFORMATION ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

Unknown 

Interpretation unknown. 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

EndOfFile 

The number of bytes from the beginning to the end of the file. 

AllocationSize 

The number of bytes allocated to the file. 

FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 
FILE_ATTRIBUTE_HIDDEN 
FILE ATTRIBUTE SYSTEM 
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FILE_ATTRIBUTE_DIRECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_DEVICE 

FI LE_ATTR I BUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FI LE_ATTR I BUTE_SPARSE_F I LE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_NOT_CONTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



FileNameLength 

The size in bytes of the FileName. 

FileName 

The name of the file. 

Remarks 

None. 



FileFullDirectorylnformation 



typedef struct _FILE_FULL_DIRECTORY_INFORMATION { // Information Class 2 
ULONG NextEntryOff set ; 

ULONG Unknown; 

LARGE_INTEGER CreationTime ; 

LARGE_INTEGER LastAccessTime; 

LARGE_INTEGER LastWriteTime ; 

LARGE_INTEGER ChangeTime; 

LARGE_INTEGER EndOfFile; 

LARGE_INTEGER AllocationSize; 

ULONG FileAttributes; 

ULONG FileNameLength; 

ULONG EalnformationLength; 

WCHAR FileName [ 1 ] ; 

} FILE_FULL_DIRECTORY_INFORMATION , *PFILE_FULL_DIRECTORY_INFORMATION ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

Unknown 

Interpretation unknown. 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 
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Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

EndOJFile 

The number of bytes from the beginning to the end of the file. 

AllocationSize 

The number of bytes allocated to the file. 



FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 
FILE_ATTRIBUTE_HIDDEN 
FI LE_ATTR I BUTE_SYSTEM 
FI LE_ATTR I BUTE_DI RECTORY 
FILE_ATTRIBUTE_ARCHIVE 
FILE_ATTRIBUTE_DEVICE 
FI LE_ATTR I BUTE_N0RMAL 

file_attribute_temporary 

F I L E_ATTR I B UT E_S P AR S E_F I L E 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_N0T_C0NTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



FileNameLength 

The size in bytes of the name of the file. 

EalnformationLength 

The size in bytes of the extended attributes of the file. 

FileName 

The name of the file. 



Remarks 

None. 
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FileBothDirectorylnformation 



typedef struct _FILE_BOTH_DIRECTORY_INFORMATION { // Information Class 3 
ULONG NextEntryOff set ; 

ULONG Unknown; 

LARGE_INTEGER CreationTime ; 

LARGE_INTEGER LastAccessTime; 

LARGE_INTEGER LastWriteTime; 

LARGE_INTEGER ChangeTime; 

LARGE_INTEGER EndOfFile; 

LARGE_INTEGER AllocationSize; 

ULONG FileAttributes; 

ULONG FileNameLength; 

ULONG EalnformationLength; 

UCHAR AlternateNameLength; 

WCHAR AlternateName[ 12] ; 

WCHAR FileName[1 ] ; 

} FILE_BOTH_DIRECTORY_INFORMATION , *PFILE_BOTH_DIRECTORY_INFORMATION ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

Unknown 

Interpretation unknown. 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

EndOfFile 

The number of bytes from the beginning to the end of the file. 

AllocationSize 

The number of bytes allocated to the file. 
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FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 

FILE_ATTRIBUTE_HIDDEN 

FILE_ATTRIBUTE_SYSTEM 

FI LE_ATTR I BUTE_DI RECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_DEVICE 

FILE_ATTRIBUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FILE_ATTRIBUTE_SPARSE_FILE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_NOT_CONTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



FileNameLength 

The size in bytes of the name of the file. 

EalnformationLength 

The size in bytes of the extended attributes of the file. 

AlternateNameLength 

The size in bytes of the alternate (short DOS 8.3 alias) name of the file. 

AlternateName 

The alternate (short DOS 8.3 alias) name of the file. 

FileName 

The name of the file. 

Remarks 

None. 



FileBasicInformation 



typedef struct _FILE_BASIC_INFORMATION { // Information Class 4 
LARGE_INTEGER CreationTime ; 

LARGE_INTEGER LastAccessTime; 

LARGE_INTEGER LastWriteTime ; 

LARGE_INTEGER ChangeTime; 

ULONG FileAttributes; 

} FILE_BASIC_INFORMATION, *PFILE_BASIC_INFORMATION ; 

Members 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 
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Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 

ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 



FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 

FILE_ATTRIBUTE_HIDDEN 

FILE_ATTRIBUTE_SYSTEM 

FI LE_ATTR I BUTE_DI RECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_DEVICE 

FILE_ATTRIBUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FI LE_ATTR I BUTE_SPARSE_FI LE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_N0T_C0NTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



Remarks 

FILE_BASIC_INFORMATION is documented in the DDK. 



FileStandardlnformation 



typedef struct _FILE_STANDARD_INFORMATION { // Information Class 5 
LARGE_INTEGER AllocationSize; 

LARGE_INTEGER EndOfFile; 

ULONG NumberOf Links; 

BOOLEAN DeletePending; 

BOOLEAN Directory; 

} FILE_STANDARD_INFORMATION, *PFILE_STANDARD_INFORMATION ; 

Members 

AllocationSize 

The number of bytes allocated to the file. 

EndOfFile 

The number of bytes from the beginning to the end of the file. 
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NumberOfLinks 

The number of directories in which the file appears. 

DeletePending 

Indicates whether the file will be deleted when the last handle to it is closed. 

Directory 

Indicates whether the file is a directory. 

Remarks 

FILE_STANDARD_INFORMATION is documented in the DDK. 



Filelnternallnformation 



typedef struct _FILE_INTERNAL_INFORMATION { // Information Class 6 
LARGE_INTEGER Fileld; 

} FILE_INTERNAL_INFORMATION, *PFILE_INTERNAL_INFORMATION ; 

Members 

Fileld 

A numeric identifier for the file. 

Remarks 

The Fileld can be used to open the file, when the FILE_OPEN_BY_FILE_ID 
CreateOption is specified in a call to ZwCreateFile. 



FileEalnformation 



typedef struct _FILE_EA_INFORMATION { // Information Class 7 
ULONG EalnformationLength; 

} FILE_EA_INFORMATION, *PFILE_EA_INFORMATION ; 

Members 

EalnformationLength 

The size in bytes of the extended attributes of the file. 

Remarks 

None. 



FileAccessInformation 



typedef struct _FILE_ACCESS_INFORMATION { // Information Class 8 
ACCESS_MASK GrantedAccess ; 

} FILE_ACCESS_INFORMATION, *PFILE_ACCESS_INFORMATION ; 
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Members 

GrantedAccess 

The access granted to the file by the handle used to perform the query. 

Remarks 

None. 



FileNamelnformation 



typedef struct _FILE_NAME_INFORMATION { // Information Classes 9 and 21 
ULONG FileNameLength; 

WCHAR FileName[1] ; 

} FILE_NAME_INFORMATION, *PFILE_NAME_INFORMATION , 

FILE_ALTERNATE_NAME_INFORMATION, *PFILE_ALTERNATE_NAME_INFORMATION; 



Members 

FileNameLength 

The size in bytes of the name of the file. 
FileName 

The name of the file. 



Remarks 

The alternate name of a file is its short DOS 8.3 alias. 



FileRenamelnformation and FileLinklnformation 



typedef struct _FILE_LINK_RENAME_INFORMATION { // Info Classes 10 and 11 
BOOLEAN Replacelf Exists; 

HANDLE RootDirectory ; 

ULONG FileNameLength; 

WCHAR FileName [ 1 ] ; 

} FILE_LINK_INFORMATION, *PFILE_LINK_INFORMATION , 

FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION ; 

Members 

ReplacelJExists 

Indicates whether an existing file with the same name as FileName should be deleted. 



RootDirectory 

A handle to the directory to which the FileName is relative. 

FileNameLength 

The size in bytes of the FileName. 
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FileName 

The name of the file. 

Remarks 

None. 



FileNamesInformation 


typedef struct _FILE_NAMES_I NFORMATION { // Information Class 12 
ULONG NextEntryOff set ; 

ULONG Unknown; 

ULONG FileNameLength; 

WCHAR FileName [ 1 ] ; 

} FILE_NAMES_INF0RMATI0N, *PFILE_NAMES_INF0RMATI0N ; 


Members 




NextEntry Offset 

The number of bytes that must be skipped to 
indicates that this is the last entry. 


get to the next entry. A value of zero 


Unknown 

Interpretation unknown. 




FileNameLength 

The size in bytes of the FileName. 




FileName 

The name of the file. 




Remarks 




None. 




FileDispositionlnformation 



typedef struct _FILE_DISP0SITI0N_INF0RMATI0N { // Information Class 13 
BOOLEAN DeleteFile; 

} FILE_DISP0SITI0N_INF0RMATI0N , *PFILE_DISP0SITI0N_INF0RMATI0N ; 



Members 

DeleteFile 

Indicates whether the file should be deleted. 



Remarks 



FILE DISPOSITION INFORMATION is documented in the DDK. 
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FilePositionlnformation 



typedef struct _FILE_P0SITI0N_INF0RMATI0N { // Information Class 14 
LARGE_INTEGER CurrentByteOf f set ; 

} FILE_P0SITI0N_INF0RMATI0N , *PFILE_POSITION_INFORMATION ; 

Members 

CurrentByteOffset 

The offset, in bytes, of the file pointer from the beginning of the file. 

Remarks 

FILE POSITION INFORMATION is documented in the DDK. 



FileModelnformation 



typedef struct _FILE_MODE_INFORMATION { // Information Class 16 
ULONG Mode; 

} FILE_MODE_INFORMATION, *PFILE_MODE_INFORMATION ; 

Members 

Mode 

The options associated with the file via the ZwCreateFile CreateOptions parameter or 
the ZwOpenFile OpenOptions parameter. 

Remarks 

The options FILE_WRITE_THROUGH, FILE_SEQUENTIAL_ONLY, FILE_SYNCHRONOUS_IO_ALERT 
and FILE_SYNCHRONOUS_IO_NONALERT can be set. Setting FILE_SYNCHRONOUS_IO_ALERT or 
FILE_SYNCHRONOUS_IO_NONALERT is only possible if the file was opened for synchronous 
I/O and just toggles the alertability of the file object. 



FileAlignmentlnformation 



typedef struct _FILE_ALIGNMENT_INFORMATION { // Information Class 17 
ULONG AlignmentRequirement ; 

} FILE_ALIGNMENT_INFORMATION, *PFILE_ALIGNMENT_INFORMATION ; 

Members 



AlignmentRequirement 

The required buffer alignment. Possible values include: 

FILE_BYTE_ALIGNMENT 
FILE_WORD_ALIGNMENT 
FILE_LONG_ALIGNMENT 
F I L E_QU AD_AL I G N M E NT 
FILE_OCTA_ALIGNMENT 
FILE_32_BYTE_ALIGNMENT 
FILE_64_BYTE_ALIGNMENT 
FILE_1 28_BYTE_ALIGNMENT 
FILE 512 BYTE ALIGNMENT 
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Remarks 

FILEALIGNMENT INFORMATION is documented in the DDK. 



FileAllInformation 



typedef struct _FILE_ALL_INFORMATION { // Information Class 18 
FILE_BASIC_INFORMATION Basiclnf ormation ; 
FILE_STANDARD_INFORMATION Standardlnf ormation ; 
FILE_INTERNAL_INFORMATION Internallnf ormation ; 
FILE_EA_INFORMATION Ealnf ormation ; 

FILE_ACCESS_INFORMATION Accesslnf ormation ; 
FILE_P0SITI0N_INF0RMATI0N Positionlnf ormation ; 
FILE_MODE_INFORMATION Modelnf ormation ; 
FILE_ALIGNMENT_INFORMATION Alignmentlnf ormation ; 
FILE_NAME_INFORMATION Namelnf ormation ; 

} FILE_ALL_INFORMATION, *PFILE_ALL_INFORMATION ; 

Remarks 

F I LE_ALL_IN FORMATION is a collection of other information classes. 



FileAllocationlnformation 



typedef struct _FILE_ALLOCATION_INFORMATION { // Information Class 19 
LARGE_INTEGER AllocationSize; 

} FILE_ALLOCATION_INFORMATION, *PFILE_ALLOCATION_INFORMATION ; 

Members 

AllocationSize 

The number of bytes allocated to the file. 



Remarks 

None. 



FileEndOfFilelnformation 



typedef struct _FILE_END_OF_FILE_INFORMATION { // Information Class 20 
LARGE_INTEGER EndOfFile; 

} FILE_END_OF_FILE_INFORMATION, *PFILE_END_OF_FILE_INFORMATION ; 

Members 

EndOfFile 

The number of bytes from the beginning to the end of the file. 

Remarks 

FILE END OF FILE INFORMATION is documented in the DDK. 
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FileS treamlnformation 



typedef struct _FILE_STREAM_INFORMATION { // Information Class 22 
ULONG NextEntryOff set ; 

ULONG StreamNameLength; 

LARGE_INTEGER EndOfStream; 

LARGE_INTEGER AllocationSize; 

WCHAR StreamName[ 1 ] ; 

} FILE_STREAM_INFORMATION, *PFILE_STREAM_INFORMATION ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. A value of zero 
indicates that this is the last entry. 

StreamNameLength 

The size in bytes of the name of the stream. 

EndOfStream 

The number of bytes from the beginning to the end of the stream. 

AllocationSize 

The number of bytes allocated to the stream. 

StreamName 

The name of the stream. 

Remarks 

None. 



FilePipelnformation 



typedef struct _FILE_PIPE_INFORMATION { // Information Class 23 
ULONG ReadModeMessage; 

ULONG WaitModeBlocking; 

} FILE_PIPE_INFORMATION, *PFILE_PIPE_INFORMATION ; 

Members 

ReadModeMessage 

A boolean specifying whether the pipe read mode is message (if true) or byte (if false). 
WaitModeBlocking 

A boolean specifying whether the pipe wait mode is blocking (if true) or no wait (if 
false) . 

Remarks 

The Win32 functions GetNamedPipeHandleState and SetNamedPipeHandleState use this 
information class. 
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FilePipeLocallnformation 



typedef struct _FILE_PIPE_LOCAL_INFORMATION { // Information Class 24 
ULONG MessageType; 

ULONG Unknownl ; 

ULONG Maxlnstances; 

ULONG Curlnstances; 

ULONG InBufferSize; 

ULONG Unknown2; 

ULONG OutBufferSize; 

ULONG Unknown3[2] ; 

ULONG ServerEnd; 

} FILE_PIPE_LOCAL_INFORMATION, *PFILE_PIPE_LOCAL_INFORMATION ; 

Members 

MessageType 

A boolean specifying whether the pipe is a message type pipe (if true) or a byte mode 
pipe (if false). 

Unknown 1 

Interpretation unknown. 

Maxlnstances 

The maximum number of instances of the pipe that are allowed. 

Curlnstances 

The current number of instances of the pipe. 

InBufferSize 

The size in bytes of the pipe input buffer. 

Unknown2 

Interpretation unknown. 

OutBufferSize 

The size in bytes of the pipe output buffer. 

Unknown3 

Interpretation unknown. 

ServerEnd 

A boolean specifying whether the pipe handle refers to the server end (if true) or 
client end (if false) of the pipe. 



Remarks 

The Win32 functions GetNamedPipelnfo and GetNamedPipeHandleState use this infor- 
mation class. 
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FilePipeRemotelnformation 



typedef struct _FI LE_P I PE_REMOTE_INFORMATION { // Information Class 25 
LARGE_INTEGER CollectDataTimeout ; 

ULONG MaxCollectionCount ; 

} FILE_PIPE_REMOTE_INFORMATION, *PFILE_PIPE_REMOTE_INFORMATION ; 

Members 

CollectDataTimeout 

The maximum time, in units of 100-nanoseconds, that can elapse before the data is 
transmitted over the network. 

MaxCollectionCount 

The maximum number of bytes that can be collected before the data is transmitted 
over the network. 

Remarks 

The Win32 functions GetNamedPipeHandleState and SetNamedPipeHandleState use this 
information class. 



FileMailsIotQuerylnformation 



typedef struct _FILE_MAILSLOT_QUERY_INFORMATION { // Information Class 26 
ULONG MaxMessageSize; 

ULONG Unknown; 

ULONG NextSize; 

ULONG MessageCount ; 

LARGE_INTEGER ReadTimeout; 

} FILE_MAILSLOT_QUERY_INFORMATION , *PFILE_MAILSLOT_QUERY_INFORMATION ; 

Members 

MaxMessageSize 

The maximum size, in bytes, of a single message that can be written to the mailslot. 

Unknown 

Interpretation unknown. 

NextSize 

The size in bytes of the next message to be read from the mailslot. If no message is 
available then NextSize is set to MAILSLOT_NO_MESSAGE. 

MessageCount 

The number of messages queued to the mailslot. 

ReadTimeout 

The maximum time, in units of 100-nanoseconds, that can elapse between starting to 
read from the mailslot and a message becoming available. 
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Remarks 

The Win32 function GetMailslotlnfo uses this information class. 



FileMailslotSetlnformation 



typedef struct _FILE_MAILSLOT_SET_INFORMATION { // Information Class 27 
LARGE_INTEGER ReadTimeout; 

} FILE_MAILSLOT_SET_INFORMATION, *PFILE_MAILSLOT_SET_INFORMATION; 

Members 

ReadTimeout 

The maximum time, in units of 100-nanoseconds, that can elapse between starting to 
read from the mailslot and a message becoming available. 



Remarks 

The Win32 function SetMailslotlnfo uses this information class. 



FileCompressionlnformation 



typedef struct _FILE_COMPRESSION_INFORMATION { // Information Class 28 
LARGE_INTEGER CompressedSize; 

USHORT CompressionFormat ; 

UCHAR CompressionUnitShift ; 

UCHAR Unknown; 

UCHAR ClusterSizeShift ; 

} FILE_COMPRESSION_INFORMATION , *PFILE_COMPRESSION_INFORMATION ; 

Members 

CompressedSize 

The size in bytes of the space occupied by a compressed file. 

CompressionFormat 

The compression algorithm used to compress the file. Defined values include: 

C0MPRESSI0N_F0RMAT_N0NE 
COMPRESSION_FORMAT_LZNT 1 

Compression UnitShift 

The size of a compression unit expressed as the logarithm to the base two of the num- 
ber of bytes in a compression unit. This member is only valid when CompressionFormat 
is not COMPRESSION_FORMAT_NONE. 

Unknown 

Interpretation unknown. This member always contains the value 12 when 
CompressionFormat is not COMPRESSION_FORMAT_NONE. Possibly the logarithm to the base 
two of the number of bytes in a page. 
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ClusterSizeShift 

The size of a cluster expressed as the logarithm to the base two of the number of bytes 
in a cluster. This member is only valid when CompressionFormat is not 
COMPRESSION_FORMAT_NONE. 

Remarks 

None. 



FileObjectldlnformation 



This information class is not implemented by any of the supported file systems. The 
file system control operations FSCTL_SET_OBJECT_ID, FSCTL_GET_OBJECT_ID, and 
FSCTL_CREATE_OR_GET_OBJECT_ID are possibly the preferred mechanisms for accessing 
this functionality. 



FileCompletionlnformation 



typedef struct _FILE_COMPLETION_INFORMATION { // Information Class 30 
HANDLE IoCompletionHandle; 

ULONG CompletionKey; 

} FILE_COMPLETION_INFORMATION, *PFILE_COMPLETION_INFORMATION ; 

Members 

IoCompletionHandle 

A handle to an I/O completion object. The handle must grant 
IO_COMPLETION_MODIFY_STATE access. 

CompletionKey 

A value to be returned to a caller of ZwRemoveloCompletion via the CompletionKey 
parameter of that routine. 

Remarks 

None. 



FileMoveClusterlnformation 



This information class is not implemented by any of the supported file systems. The 
file system control operation FSCTL_MOVE_FILE is possibly the preferred mecha- 
nism for accessing this functionality. 



FileQuotalnformation 



This information class is not implemented by any of the supported file systems. The 
native system services ZwQueryQuotalnformationFile and ZwSetQuotalnformationFile 

are possibly the preferred mechanisms for accessing this functionality. 
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FileReparsePointlnformation 



This information class is not implemented by any of the supported file systems. The 
file system control operations FSCTL_SET_REPARSE_POINT, FSCTL_GET_REPARSE_POINT and 
FSCTL_DELETE_REPARSE_POINT are possibly the preferred mechanisms for accessing this 
functionality. 



FileNetworkOpenlnformation 



typedef struct _FILE_NETWORK_OPEN_INFORMATION { // Information Class 34 
LARGE_INTEGER CreationTime ; 

LARGE_INTEGER LastAccessTime; 

LARGE_INTEGER LastWriteTime; 

LARGE_INTEGER ChangeTime; 

LARGE_INTEGER AllocationSize; 

LARGE_INTEGER EndOfFile; 

ULONG FileAttributes; 

} FILE_NETWORK_OPEN_INFORMATION, *PFILE_NETWORK_OPEN_INFORMATION; 

Members 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

AllocationSize 

The number of bytes allocated to the file. 

EndOfFile 

The number of bytes from the beginning to the end of the file. 



FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 
FILE_ATTRIBUTE_HIDDEN 
FILE_ATTRIBUTE_SYSTEM 
FI LE_ATTR I BUTE_D I RECTORY 
FILE_ATTRIBUTE_ARCHIVE 
FILE ATTRIBUTE DEVICE 
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FI LE_ATTR I BUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FI LE_ATTR I BUTE_SPARSE_F I LE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_NOT_CONTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



Remarks 

None. 



FileAttributeTaglnformation 



typedef struct _FILE_ATTRIBUTE_TAG_INFORMATION {// Information Class 35 
ULONG FileAttributes; 

ULONG ReparseTag; 

} F I LE_ATTR I BUTE_TAG_I N FORMAT I ON , * P F I L E_ATT R I B UT E_T AG_I N FORMATION ; 

Members 

FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 

FILE_ATTRIBUTE_HIDDEN 

FILE_ATTRIBUTE_SYSTEM 

FI LE_ATTR I BUTE_DI RECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_DEVICE 

FI LE_ATTR I BUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

FILE_ATTRIBUTE_SPARSE_FILE 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_NOT_CONTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



ReparseTag 

The reparse tag, if any, of the file. The format of reparse tags is defined in winnt.h. 

Remarks 

None. 



Example 13.1: Opening a File by File ID 



#include "ntdll.h" 

int main(int argc, char *argv[]) 

{ 

HANDLE hFilel = CreateFile(argv[ 1 ] , GENERIC_READ, F I L E_S H AR E_R E AD , 0, 
OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL , 0); 
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NT : : I0_STATUS_BL0CK iosb; 

NT: : FILE_INTERNAL_INFORMATION fii; 

NT: :ZwQueryInformationFile(hFile1 , &iosb, &fii, sizeof fii, 

NT : :FileInternalInformation) ; 

NT: :UNICODE_STRING name = {sizeof fii.Fileld, sizeof fii.Fileld, 
PWSTR (&f ii . Fileld ) } ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa, hFilel , &name}; 

HANDLE hFile2; 



NT: :Zw0penFile(&hFile2, GENERIC_READ j SYNCHRONIZE, &oa, &iosb, 

F I L E_S H AR E_R E AD , 

FILE_SYNCHRONOUS_IO_NONALERT | FILE_OPEN_BY_FILE_ID) ; 

CloseHandle(hFile1 ) ; 

CHAR buf [400] ; ULONG n; 

ReadFile(hFile2, buf, sizeof buf, &n, 0); 
WriteFile(GetStdHandle(STD_OUTPUT_HANDLE) , buf, n, &n, 0); 

CloseHandle(hFile2) ; 

return 0; 

} 

When opening a file by file identifier, the ObjectName member of the 
Ob j ectAttributes parameter to ZwCreateFile points to the file identifier, and the 
RootDirectory member contains a handle that is used to identify the volume. This 
handle can either be a handle to the volume or to any file on the volume. Not all file 
systems support FILE_OPEN_BY_FILE_ID, but NTFS does. 
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Registry Keys 



The system services described in this chapter create and manipulate registry key 
objects. 

Key handles to registry keys on remote systems are implemented entirely in user mode 
and are not valid handles for the system services described in this chapter. 



ZwCreateKey 



ZwCreateKey creates or opens a registry key object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreateKey( 

OUT PHANDLE KeyHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Obj ectAttributes , 

IN ULONG Titlelndex, 

IN PUNICODE_STRING Class OPTIONAL, 

IN ULONG CreateOptions, 

OUT PULONG Disposition OPTIONAL 

); 



Parameters 

KeyHandle 

Points to a variable that will receive the key object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the key object. This parameter 
can be zero, or any combination of the following flags: 



KEY_QUERY_VALUE 

KEY_SET_VALUE 

KEY_CREATE_SUB_KEY 

KEY_ENUMERATE_SUB_KEYS 

KEY_NOTIFY 

KEY_CREATE_LINK 

KEY_ALL_ACCESS 



Values of key can be queried 
Values of key can be set 
Subkeys can be created in the key 
Subkeys of key can be enumerated 
Key can be monitored 
Not used 

All of the preceding + 

STANDARD RIGHTS REQUIRED 
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Object Attributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. 

Titlelndex 

Not used. 



Class 

Optionally points to a string that will be stored in the key. 



Create Options 

Specifies options that affect the creation of the key. Permitted values are: 

REG_0PTI0N_V0LATILE 0x00000001 L 

REG_OPTION_CREATE_LINK 0X00000002L 

REG_OPTION_BACKUP_RESTORE 0X00000004L 
REG_0PTI0N_0PEN_LINK 0X00000008L 



Disposition 

Optionally points to a variable that receives an indication of whether the key was cre- 
ated or opened. The values returned are: 

REG_CREATED_NEW_KEY 0x00000001 L 

REG_OPENED_EXISTING_KEY 0X00000002L 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_OBJECT_TYPE_MISMATCH, STATUS_OBJECT_NAME_NOT_FOUND, 
STATUS_KEY_DELETED, STATUS_NO_LOG_SPACE, or STATUS_CHILD_MUST_BE_VOLATILE. 

Related Win32 Functions 

RegCreateKey, RegCreateKeyEx. 

Remarks 

ZwCreateKey is documented in the DDK. 

A registry symbolic link is created by first creating a key with the option 
REG_OPTION_CREATE_LINK and then using ZwSetValueKey with a type of MG_LINK 
and value name of “SymbolicLinkValue” to point to another key. The link data should 
not include the zero-terminating character. 

A symbolic link can be opened by specifying the attribute OBJ_OPENLINK in 
ObjectAttributes. REG_OPTION_OPEN_LINK appears to have no effect. 



ZwOpenKey 



ZwOpenKey opens a registry key object. 

NTSYSAPI 

NTSTATUS 

NTAPI 
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ZwOpenKey ( 

OUT PHANDLE KeyHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_ATTRIBUTES Ob j ectAttributes 

); 



Parameters 

KeyHandle 

Points to a variable that will receive the key object handle if the call is successful. 



DesiredAccess 

Specifies the type of access that the caller requires to the key object. This parameter 
can be zero, or any combination of the following flags: 



KEY_QUERY_VALUE 

KEY_SET_VALUE 

KEY_CREATE_SUB_KEY 

KEY_ENUMERATE_SUB_KEYS 

KEY_NOTIFY 

KEY_CREATE_LINK 

KEY_ALL_ACCESS 



Values of key can be queried 
Values of key can be set 
Subkeys can be created in the key 
Subkeys of key can be enumerated 
Key can be monitored 
Not used 

All of the preceding + 
STANDARD_RIGHTS_REQUIRED 



Obj ectAttributes 

Points to a structure that specifies the objects attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_OBJECT_TYPE_MISMATCH, STATUS_OBJECT_NAME_NOT_FOUND, 
or STATUS_KEY_DELETED. 

Related Win32 Functions 

RegOpenKey, RegOpenKeyEx. 

Remarks 

ZwOpenKey is documented in the DDK. 



Z wD eleteKey 



ZwDeleteKey deletes a key in the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeleteKey ( 

IN HANDLE KeyHandle 

); 
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Parameters 

KeyHandle 

A handle to a key object. The handle must grant DELETE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, or STATUS_CANNOT_DELETE. 

Related Win32 Functions 

RegDeleteKey. 

Remarks 

ZwDeleteKey is documented in the DDK. 



ZwFlushKey 



ZwFlushKey flushes changes to a key to disk. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFlushKey ( 

IN HANDLE KeyHandle 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle need not grant any specific access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_KEY_DELETED, or STATUS_REGISTRY_IO_FAILED. 

Related Win32 Functions 

RegFlushKey. 

Remarks 

ZwFlushKey is documented in the DDK. 



ZwSaveKey 



ZwSaveKey saves a copy of a key and its subkeys in a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 
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ZwSaveKey ( 

IN HANDLE KeyHandle, 

IN HANDLE FileHandle 

); 

Parameters 

KeyHandle 

A handle to a key object. The handle need not grant any specific access. 

FileHandle 

A handle to the file object in which the key is to be saved. The handle should grant 
FILE_GENERIC_WRITE access. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAILED, or 
STATUS_KEY_DELETED. 

Related Win32 Functions 

RegSaveKey. 

Remarks 

SeBackupPrivilege is required to save a key. 



ZwSaveMergedKeys 



ZwSaveMergedKeys merges two keys and their subkeys and saves the result in a file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSaveMergedKeys ( 

IN HANDLE KeyHandlel , 

IN HANDLE KeyHandle2, 

IN HANDLE FileHandle 

); 

Parameters 

KeyHandle 1 

A handle to a key object. The handle need not grant any specific access. 

KeyHandlel 

A handle to a key object. The handle need not grant any specific access. 

FileHandle 

A handle to the file object in which the key is to be saved. The handle should grant 
FILE GENERIC WRITE access. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAI LED, or 
STATUS_KEY_DELETED. 

Related Win32 Functions 

None. 

Remarks 

SeBackupPrivilege is required to save a key. 

The keys identified by KeyHandlel and KeyHandle2 must be stored in separate hives. 
The routine ZwSaveMergedKeys is only present in Windows 2000. 



ZwRestoreKey 



ZwRestoreKey restores a key saved in a file to the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRestoreKey ( 

IN HANDLE KeyHandle, 

IN HANDLE FileHandle, 

IN ULONG Flags 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle need not grant any specific access. 

FileHandle 

A handle to the file object in which the key is to be saved. The handle should grant 
FILE_GENERIC_READ access. 

Flags 

Specifies options that affect the restoration of the key. Permitted values are: 

REG_WH0LE_HIVE_V0LATILE 

REG_REFRESH_HIVE 

REG_F0RCE_REST0RE // Windows 2000 only 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAILED, 
STATUS_CANNOT_DELETE, STATUS_KEY_DELETED, STATUS_INSUFFICIENT_RESOURCES or 
STATUS REGISTRY CORRUPT. 
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Related Win32 Functions 

RegRestoreKey. 



Remarks 

SeRestorePrivilege is required to restore a key. 



ZwLoadKey 



ZwLoadKey mounts a key hive in the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwLoadKey ( 

IN POBJECT_ATTRIBUTES KeyObj ectAttributes , 
IN POBJECT_ATTRIBUTES FileObj ectAttributes 
); 



Parameters 

Key Object A ttributes 

Points to a structure that specifies the key objects attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. 

File Object A ttributes 

Points to a structure that specifies the file object’s attributes. OBJ_PERMANENT, 
OBJ_EXCLUSIVE and OBJ_OPENLINK are not valid attributes for a file object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAILED, 
STATUS_INSUFFICIENT_RESOURCES, or STATUS_REGISTRY_CORRUPT. 

Related Win32 Functions 

RegLoadKey. 

Remarks 

SeRestorePrivilege is required to load a key. 

ZwLoadKey is equivalent to ZwLoadKey2 with a flags argument of zero. 



Z wLo adKey 2 



ZwLoadKey2 mounts a key hive in the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 
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ZwLoadKey2( 

IN POBJECT_ATTRIBUTES KeyObj ectAttributes , 

IN POBJECT_ATTRIBUTES FileObj ectAttributes 
IN ULONG Flags 
); 

Parameters 

Key Object A ttributes 

Points to a structure that specifies the key objects attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. 

File Object A ttributes 

Points to a structure that specifies the file object’s attributes. OBJ_PERMANENT, 
OBJ_EXCLUSIVE and 0BJ_0PENLINK are not valid attributes for a file object. 

Flags 

Specifies options that affect the restoration of the key. Permitted values are: 
REG_NO_LAZY_FLUSH 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAILED, 
STATUS_INSUFFICIENT_RESOURCES, or STATUS_REGISTRY_CORRUPT. 

Related Win32 Functions 

None. 

Remarks 

SeRestorePrivilege is required to load a key. 



ZwUnloadKey 



ZwUnloadKey dismounts a key hive in the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwUnloadKey ( 

IN POBJECT_ATTRIBUTES KeyObj ectAttributes 

); 



Parameters 

KeyObjectAttributes 

Points to a structure that specifies the key object’s attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 

STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD or STATUS_REGISTRY_IO_FAILED. 

Related Win32 Functions 

RegUnloadKey. 

Remarks 

SeRestorePrivilege is required to unload a key. 



ZwQueryOpenSubKeys 



ZwQueryOpenSubKeys reports on the number of open keys in a hive. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryOpenSubKeys ( 

IN POBJECT_ATTRIBUTES KeyObj ectAttributes , 

OUT PULONG NumberOfKeys 

); 



Parameters 

Key Obj ectAttributes 

Points to a structure that specifies the key object’s attributes. OBJ_PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. The key referred to by 
KeyObj ectAttributes must be the root of a hive. 

NumberOfKeys 

Points to a variable that receives the number of open keys in the hive. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_PARAMETER. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwQueryOpenSubKeys is only present in Windows 2000. 
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ZwReplaceKey 



ZwReplaceKey replaces a mounted key hive with another. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwReplaceKey ( 

IN POBJECT_ATTRIBUTES NewFileObj ectAttributes , 

IN HANDLE KeyHandle, 

IN POBJECT_ATTRIBUTES OldFileObj ectAttributes 

); 



Parameters 

NewFileObjectA ttribu tes 

Points to a structure that specifies the file object’s attributes. OBJ_PERMANENT, 
OBJ_EXCLUSIVE, and 0BJ_0PENLINK are not valid attributes for a file object. 

KeyHandle 

A handle to a key object. The handle need not grant any specific access. 

OldFileObjectAttributes 

Points to a structure that specifies the file object’s attributes. OBJ PERMANENT, 
OBJ_EXCLUSIVE, and 0BJ_0PENLINK are not valid attributes for a file object. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, STATUS_REGISTRY_IO_FAILED, 
STATUS_INSUFFICIENT_RESOURCES, or STATUS_REGISTRY_CORRUPT. 

Related Win32 Functions 

RegReplaceKey. 

Remarks 

SeRestorePrivilege is required to replace a key. 



ZwSetlnformationKey 



ZwSetlnformationKey sets information affecting a key object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetlnformationKey ( 

IN HANDLE KeyHandle, 

IN KEY_SET_INFORMATION_CLASS Keylnf ormationClass , 

IN PVOID Keylnformation, 

IN ULONG KeylnformationLength 

); 
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Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_SET_VALUE access. 

Key Information Class 

Specifies the type of key object information to be set. The permitted values are drawn 
from the enumeration KEY_SET_INFORMATION_CLASS, described in the following section. 

Keylnformation 

Points to a caller-allocated buffer or variable that receives the key object information 
to be set. 

KeylnformationLength 

The size in bytes of Keylnformation, which the caller should set according to the given 
Key Inf ormationClass. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or ST ATUS_I N F0_L ENGTH_M I SMATCH . 

Related Win32 Functions 

None. 

Remarks 

None. 



KEY_SET_INFORMATION_CLASS 



typedef enum _KEY_SET_INFORMATION_CLASS { 
KeyLastWriteTimelnformation 
} KEY_SET_INFORMATION_CLASS; 



KeyLastWriteTimelnformation 



typedef struct _KEY_LAST_WRITE_TIME_INFORMATION { 

LARGE_INTEGER LastWriteTime ; 

} KEY_LAST_WRITE_TIME_INFORMATION, *PKEY_LAST_WRITE_TIME_INFORMATION; 

Members 

LastWriteTime 

The last time the key or any of its values changed in the standard time format (that is, 
the number of 100-nanosecond intervals since January 1, 1601). 

Remarks 

None. 
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ZwQueryKey 



ZwQueryKey retrieves information about a key object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryKey ( 

IN HANDLE KeyHandle, 

IN KEY_INFORMATION_CLASS Keylnf ormationClass , 

OUT PVOID Key I information, 

IN ULONG KeylnformationLength, 

OUT PULONG ResultLength 

); 

Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_QUERY_VALUE access, except when 
querying KeyNamelnformation when no specific access is required. 

Key Information Class 

Specifies the type of key object information to be queried. The permitted values are 
drawn from the enumeration KEY_INFORMATION_CLASS, described in the following 
section. 

Key Information 

Points to a caller-allocated buffer or variable that receives the requested key object 
information. 

KeylnformationLength 

The size in bytes of Key Inf or mat ion, which the caller should set according to the given 
Keylnf ormationClass. 

ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
Keylnf ormation if the call was successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_I NVAL I D_PARAMETER, or STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

RegQuerylnfoKey. 

Remarks 

ZwQueryKey is documented in the DDK. 
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ZwEnumerateKey 



ZwEnumerateKey enumerates the subkeys of a key object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwEnumerateKey ( 

IN HANDLE KeyHandle, 

IN ULONG Index, 

IN KEY_INFORMATION_CLASS Keylnf ormationClass , 

OUT PVOID Keylnformation, 

IN ULONG KeylnformationLength, 

OUT PULONG ResultLength 

); 

Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_ENUMERATE_SUB_KEYS access. 

Index 

Specifies the zero-based index of the subkey for which the information is requested. 

Keylnformation Class 

Specifies the type of key object information to be queried. The permitted values 
are drawn from the enumeration KEY_INFORMATION_CLASS, described in the following 
section. 

Keylnformation 

Points to a caller- allocated buffer or variable that receives the requested key object 
information. 

KeylnformationLength 

The size in bytes of Keylnformation, which the caller should set according to the given 
Keylnf ormationClass. 

ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
Keylnformation if the call was successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_I NVAL I D_PARAMETER, STATUS_BUFFER_TOO_SMALL, or 
STATUS_NO_MORE_ENTRIES. 

Related Win32 Functions 

RegEnumKey, RegEnumKeyEx. 

Remarks 



ZwEnumerateKey is documented in the DDK. 
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KEY_INFORMATION_CLASS 



typedef enum _KEY_IN FORMAT I ON_CLASS { 
KeyBasicInf ormation, 

KeyNodelnf ormation , 

KeyFullInf ormation , 

KeyNamelnf ormation 
} KEY_INFORMATION_CLASS; 



KeyBasicInformation 



typedef struct _KEY_BAS I CONFORMATION { 

LARGE_INTEGER LastWriteTime ; 

ULONG Titlelndex; 

ULONG NameLength; 

WCHAR Name[1]; // Variable length string 

} KEY_BAS I CONFORMATION, *PKEY_BASIC_INFORMATION ; 

Members 

LastWriteTime 

The last time the key or any of its values changed in the standard time format (that is, 
the number of 100-nanosecond intervals since January 1, 1601). 

Titlelndex 

Not used. 

NameLength 

The size in bytes of Name, including the zero-terminating character. 

Name 

A zero-terminated Unicode string naming the key. 



Remarks 

KEY_BASI CONFORMATION is documented in the DDK. 



KeyNodelnformation 



typedef struct _KEY_N0DE_INF0RMATI0N ^ 

LARGE_INTEGER LastWriteTime; 

ULONG Titlelndex; 

ULONG ClassOffset; 

ULONG ClassLength; 

ULONG NameLength; 

WCHAR Name [ 1 ] ; // Variable length string 

// Class[1]; // Variable length string not declared 

} KEY_N0DE_INF0RMATI0N, *PKEY_N0DE_INF0RMATI0N; 









1996 CH14 



12/1/99 



12:34 PM 



Page 




Registry Keys: KeyFullInformation 355 



Members 

LastWriteTime 

The last time the key or any of its values changed in the standard time format (that is, 
the number of 100-nanosecond intervals since January 1, 1601). 

Title Index 

Not used. 

Class Offset 

The offset in bytes from the start of the KEY_N0DE_INF0RMATI0N structure to the class 
name string. 



ClassLength 

The size in bytes of Class, including the zero-terminating character. 

NameLength 

The size in bytes of Name, including the zero-terminating character. 

Name 

A zero-terminated Unicode string naming the key. 

Class 

A zero-terminated Unicode string naming the key class. 

Remarks 

KEY_N0DE INFORMATION is documented in the DDK. 



KeyFullInformation 



typedef struct _KEY_FULL_INF0RMATI0N { 

LARGE_INTEGER LastWriteTime; 

ULONG Titlelndex; 

ULONG ClassOffset; 

ULONG ClassLength; 

ULONG SubKeys; 

ULONG MaxNameLen; 

ULONG MaxClassLen; 

ULONG Values; 

ULONG MaxValueNameLen; 

ULONG MaxValueDataLen; 

WCHAR Class [ 1 ] ; // Variable length string 

} KEY_FULL_INF0RMATI0N , *PKEY_FULL_INF0RMATI0N ; 

Members 

LastWriteTime 

The last time the key or any of its values changed in the standard time format (that is, 
the number of 100-nanosecond intervals since January 1, 1601). 
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Titlelndex 

Not used. 

Class Offset 

The offset in bytes from the start of the KEY_NODE_INFORMATION structure to the class 
name string. 

ClassLength 

The size in bytes of Class, including the zero-terminating character. 

SubKeys 

The number of subkeys for the key. 

MaxNameLen 

The length of the longest subkey name. 

MaxClassLen 

The length of the longest subkey class name. 

Values 

The number of value entries for the key. 

Max ValueNameLen 

The length of the longest value entry name. 

Max ValueDataLen 

The length of the longest value entry data. 

Class 

A zero-terminated Unicode string naming the key class. 

Remarks 

KEY_FULL_IN FORMATION is documented in the DDK. 



KeyNamelnformation 



typedef struct _KEY_NAME_INFORMATION { 

ULONG NameLength; 

WCHAR Name[1]; // Variable length string 

} KEY_NAME_INFORMATION, *PKEY_NAME_INFORMATION ; 

Members 

NameLength 

The size in bytes of Name, including the zero-terminating character. 

Name 

A zero-terminated Unicode string naming the key. 
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Remarks 

This information class is only available in Windows 2000. 



Z wN o tifyChangeKey 



ZwNotifyChangeKey monitors a key for changes. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwNotifyChangeKey ( 

IN HANDLE KeyHandle, 

IN HANDLE EventHandle OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PI0_STATUS_BL0CK IoStatUSBIOCk , 

IN ULONG NotifyFilter, 

IN BOOLEAN WatchSubtree , 

IN PVOID Buffer, 

IN ULONG BufferLength, 

IN BOOLEAN Asynchronous 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_NOTIFY access. 

EventHandle 

Optionally specifies a handle to an event object to signal when the operation 
completes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

PI0_STATUS_BL0CK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a caller-allocated buffer or variable that receives in the member 
IoStatusBlock . Status, which is the status of the change notification. 
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NotifyFilter 

Specifies the types of changes to be monitored. This parameter can be any combina- 
tion of the following flags: 

REG_NOTIFY_CHANGE_NAME 
REG_NOTIFY_CHANGE_ATTR I BUTES 
REG_NOTIFY_CHANGE_LAST_SET 
REG_NOTIFY_CHANGE_SECURITY 

WatchSubtree 

Specifies whether changes to all the keys in the subtree below KeyHandle should also 
be monitored. 

Buffer 

Not used. 

BufferLength 

Not used. Must be zero. 

Asynchronous 

Specifies whether ZwNotifyChangeKey should return immediately. 

Return Value 

Returns STATUS_SUCCESS, STATUS_P ENDING, STATUS_NOTIFY_CLEANUP, 

STATUS_NOTI FY_ENUM_DI R, or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, or STATUS_KEY_DELETED. 

Related Win32 Functions 

RegNot if yChangeKey Value. 

Remarks 

None. 



Z wN o tifyChangeMultipleKeys 



ZwNotifyChangeMultipleKeys monitors one or two keys for changes. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwNotifyChangeMultipleKeys ( 

IN HANDLE KeyHandle, 

IN ULONG Flags, 

IN POBJECT_ATTRIBUTES KeyObj ectAttributes , 

IN HANDLE EventHandle OPTIONAL, 

IN PI0_APC_R0UTINE ApcRoutine OPTIONAL, 

IN PVOID ApcContext OPTIONAL, 

OUT PIO_STATUS_BLOCK IoStatUSBIOCk, 

IN ULONG NotifyFilter, 

IN BOOLEAN WatchSubtree, 

IN PVOID Buffer, 

IN ULONG BufferLength, 

IN BOOLEAN Asynchronous 

); 
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Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_NOTIFY access. 

Flags 

Specifies options that affect the monitoring of the keys. Permitted values are: 

REG_MONITOR_SINGLE_KEY 0x00 
REG_MONITOR_SECOND_KEY 0x01 

Key Object Attributes 

Points to a structure that specifies a key objects attributes. OBJ PERMANENT and 
OBJ_EXCLUSIVE are not valid attributes for a key object. If Flags specifies 
REG_MONITOR_SECOND_KEY, the key identified by KeyObjectAttributes is opened for 
REG_NOTIFY access and is monitored; otherwise KeyObjectAttributes may be a null 
pointer. 

EventHandle 

Optionally specifies a handle to an event object to signal when the operation com- 
pletes. The handle must grant EVENT_MODIFY_STATE access. 

ApcRoutine 

Optionally points to a routine to execute when the operation completes. The signature 
of the routine is: 

VOID (NTAPI *PI0_APC_R0UTINE) (PVOID ApcContext, 

P 1 0_ST ATUS_B LOCK IoStatusBlock, 

ULONG Reserved) ; 



ApcContext 

A void pointer that can be used to provide the ApcRoutine with contextual 
information. 

IoStatusBlock 

Points to a caller- allocated buffer or variable that receives in the member 
IoStatusBlock. Status, whcih is the status of the change notification. 

NotifyFilter 

Specifies the types of changes to be monitored. This parameter can be any combina- 
tion of the following flags: 

REG_NOTIFY_CHANGE_NAME 
REG_NOTIFY_CHANGE_ATTR I BUTES 
REG_NOTIFY_CHANGE_LAST_SET 
REG_NOTIFY_CHANGE_SECURITY 

WatchSubtree 

Specifies whether changes to all the keys in the subtree below KeyHandle should also 
be monitored. 
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Buffer 

Not used. 

BufferLength 

Not used. Must be zero. 

Asynchronous 

Specifies whether ZwNotif yChangeMultipleKeys should return immediately. 

Return Value 

Returns STATUS_SUCCESS, STATUS_P ENDING, STATUS_NOTIFY_CLEANUP, 

ST ATUS_N0T I FY_ENUM_DI R, or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, or STATUS_KEY_DELETED. 

Related Win32 Functions 

None. 

Remarks 

The keys identified by KeyHandle and KeyObjectAttributes must be stored in separate 
hives. 

The routine ZwNotif yChangeMultipleKeys is only present in Windows 2000. 



ZwDeleteValueKey 



ZwDeleteValueKey deletes a value from a key. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeleteValueKey ( 

IN HANDLE KeyHandle, 

IN PUNIC0DE_STRING ValueName 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_SET_VALUE access. 

ValueName 

The name of the value to be deleted. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_0BJECT_NAME_N0T_F0UND, STATUS_KEY_DELETED, or 
STATUS NO LOG SPACE. 
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Related Win32 Functions 

RegDeleteValue. 

Remarks 

None. 



ZwSetValueKey 



ZwSetValueKey updates or adds a value to a key. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetValueKey ( 

IN HANDLE KeyHandle, 

IN PUNICODE_STRING ValueName, 

IN ULONG Titlelndex, 

IN ULONG Type, 

IN PVOID Data, 

IN ULONG DataSize 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_SET_VALUE access. 

ValueName 

The name of the value to be set. 



Titlelndex 

Not used. 



Type 

Specifies the data type of the value to be set. Permitted values are: 

REG_N0NE 

REG_SZ 

REG_EXPAND_SZ 

REG_BINARY 

REG_DW0RD 

R EG_DW0 R D_L I TT L E_E N D I AN 

R EG_DW0 R D_B I G_E N D I AN 

REG_LINK 

REG_MULTI_SZ 

REG_RESOURCE_LIST 

REG_FULL_RESOURCE_DESCRIPTOR 

REG_RESOURCE_REQUIREMENTS_LIST 

REG_QW0RD 

REG_QWORD_LITTLE_ENDIAN 



Data 

Points to a caller-allocated buffer or variable that contains the data of the value. 
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DataSize 

The size in bytes of Data. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_KEY_DELETED, or STATUS_NO_LOG_SPACE. 

Related Win32 Functions 

RegSetValue, RegSetValueEx. 

Remarks 

ZwSetValueKey is documented in the DDK. 



ZwQueryValueKey 



ZwQueryValueKey retrieves information about a key value. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryValueKey ( 

IN HANDLE KeyHandle, 

IN PUNICODE_STRING ValueName, 

IN KEY_VALUE_INFORMATION_CLASS KeyValuelnf ormationClass , 
OUT PVOID KeyValuelnf ormation, 

IN ULONG KeyValuelnformationLength, 

OUT PULONG ResultLength 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_QUERY_VALUE access. 

ValueName 

The name of the value to be deleted. 

Key ValuelnformationClass 

Specifies the type of key object value information to be queried. The permitted 
values are drawn from the enumeration KEY_VALUE_INFORMATION_CLASS, described in the 
following section. 

Key Valuelnf ormation 

Points to a caller- allocated buffer or variable that receives the requested key object 
value information. 

Key ValuelnformationLength 

Specifies the size in bytes of KeyValuelnformation, which the caller should set accord- 
ing to the given KeyValuelnf ormationClass. 
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ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
KeyValuelnformation if the call was successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_OBJ ECT_NAME_NOT_FOUND, STATUS_KEY_DELETED or 
STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

RegQueryValue, RegQueryValueEx. 

Remarks 

ZwQueryValueKey is documented in the DDK. 



ZwEnumerateValueKey 



ZwEnumerateValueKey enumerates the values of a key. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwEnumerateValueKey ( 

IN HANDLE KeyHandle, 

IN ULONG Index, 

IN KEY_VALUE_INFORMATION_CLASS KeyValuelnf ormationClass , 

OUT PVOID KeyValuelnformation, 

IN ULONG KeyValuelnformationLength, 

OUT PULONG ResultLength 

); 

Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_QUERY_VALUE access. 

Index 

Specifies the zero-based index of the value for which the information is requested. 

Key ValuelnformationClass 

Specifies the type of key object value information to be queried. The permitted 
values are drawn from the enumeration KEY_VALUE_INFORMATION_CLASS, described in the 
following section. 

Key Valuelnformation 

Points to a caller-allocated buffer or variable that receives the requested key object 
value information. 

Key ValuelnformationLength 

Specifies the size in bytes of KeyValuelnformation, which the caller should set accord- 
ing to the given KeyValuelnformationClass. 
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ReturnLength 

Points to a variable that receives the number of bytes actually returned to 
KeyValuelnformation if the call was successful. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_OBJ ECT_NAME_NOT_FOUND, STATUS_KEY_DELETED, 
STATUS_BUFFER_TOO_SMALL, or STATUS_NO_MORE_ENTRIES. 

Related Win32 Functions 

RegEnumValue. 

Remarks 

ZwEnumerateValueKey is documented in the DDK. 



KFYVALUHIN FORM ATIONCL ASS 



typedef enum _KEY_VALUE_INFORMATION_CLASS { KeyValueBasicInformation, 
KeyValueFullInformation, 

KeyValuePartiallnf ormation , 

KeyValueFullInformationAlign64 
} KEY_VALUE_INFORMATION_CLASS; 



KeyValueBasicInformation 



typedef Struct _KEY_VALUE_BASIC_INFORMATION { 

ULONG Titlelndex; 

ULONG Type; 

ULONG NameLength; 

WCHAR Name [ 1 ] ; // Variable length string 

} KEY_VALUE_BASIC_INFORMATION , *PKEY_VALUE_BASIC_INFORMATION ; 

Members 



Titlelndex 

Not used. 



Type 

The data type of the value. The defined values are: 

REG_N0NE 

REG_SZ 

REG_EXPAND_SZ 

REG_BINARY 

REG_DW0RD 

REG_DWORD_LITTLE_ENDIAN 

R EG_DW0 R D_B I G_E N D I AN 

REG_LINK 

REG_MULTI_SZ 

REG_RESOURCE_LIST 

REG_FULL_RESOURCE_DESCRIPTOR 

REG RESOURCE REQUIREMENTS LIST 
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REG_QW0RD 

R EG_QW0 R D_L I TT L E_E N D I AN 

NameLength 

The size in bytes of Name, including the zero-terminating character. 

Name 

A zero-terminated Unicode string naming the value. 

Remarks 

KEY_VALUE_BASIC_IN FORMATION is documented in the DDK. 



KeyValueFullInformation and 
KeyValueFullInformationAlign64 



typedef struct _KEY_VALUE_FULL_INFORMATION { 

ULONG Titlelndex; 

ULONG Type; 

ULONG DataOffset ; 

ULONG DataLength; 

ULONG NameLength; 

WCHAR Name [ 1 ] ; // Variable length string 

// Data [ 1 ] ; // Variable length data not declared 

} KEY_VALUE_FULL_INFORMATION , *PKEY_VALUE_FULL_INFORMATION ; 

Members 



Titlelndex 

Not used. 



The data type of the value. The defined values are: 

REG_N0NE 

REG_SZ 

REG_EXPAND_SZ 

REG_BINARY 

REG_DW0RD 

REG_DWORD_LITTLE_ENDIAN 

REG_DWORD_BIG_ENDIAN 

REG_LINK 

REG_MULTI_SZ 

REG_RESOURCE_LIST 

REG_FULL_RESOURCE_DESCRIPTOR 

REG_RESOURCE_REQUIREMENTS_LIST 

REG_QW0RD 

R E G_QW0 RD_LITTLE ENDIAN 



DataOffset 

The offset in bytes from the start of the KEY_VALUE_FULL_INFORMATION structure to the 
value’s data. 
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DataLength 

The size in bytes of Data. 

NameLength 

The size in bytes of Name, including the zero-terminating character. 

Name 

A zero-terminated Unicode string naming the value. 

Data 

The data of the value. 

Remarks 

KEY_VALUE_FULL_INFORMATION is documented in the DDK. 

KeyValueFullInformationAlign64 is only available in Windows 2000 and ensures that 
the Data is aligned on a 64-bit boundary. 



KeyValuePartiallnformation 



typedef struct _KEY_VALUE_PARTIAL_INFORMATION { 

ULONG Titlelndex; 

ULONG Type; 

ULONG DataLength; 

UCHAR Data [ 1 ] ; // Variable length data 

} KEY_VALUE_PARTIAL_INFORMATION , *PKEY_VALUE_PARTIAL_INFORMATION; 



Members 

Titlelndex 

Not used. 



Type 

The data type of the value. The defined values are: 

REG_N0NE 

REG_SZ 

REG_EXPAND_SZ 

REG_BINARY 

REG_DW0RD 

REG_DWORD_LITTLE_ENDIAN 

REG_DWORD_BIG_ENDIAN 

REG_LINK 

REG_MULTI_SZ 

REG_RESOURCE_LIST 

REG_FULL_RESOURCE_DESCRIPTOR 

REG_RESOURCE_REQUIREMENTS_LIST 

REG_QW0RD 

R EG_QW0 RD_LITTLE_ENDIAN 



DataLength 

The size in bytes of Data. 
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Data 

The data of the value. 

Remarks 

KEY_VALUE_PARTIAL_INFORMATION is documented in the DDK. 



ZwQueryMultipleValueKey 



ZwQueryMultipleValueKey retrieves information about multiple key values. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryMultipleValueKey ( 

IN HANDLE KeyHandle, 

IN OUT PKEY_VALUE_ENTRY ValueList, 

IN ULONG NumberOf Values, 

OUT PVOID Buffer, 

IN OUT PULONG Length, 

OUT PULONG ReturnLength 

); 



Parameters 

KeyHandle 

A handle to a key object. The handle must grant KEY_QUERY_VALUE access. 

ValueList 

Points to a caller-allocated buffer or variable that contains an array of value names to 
be queried and that receives information about the data of the values. 

NumberOfValues 

The number of elements in the ValueList. 

Buffer 

Points to a caller- allocated buffer or variable that receives the data of the values. 

Length 

Points to a variable that specifies the size in bytes of Buffer and that receives the 
number of bytes actually returned to Buffer if the call was successful. 

ReturnLength 

Points to a variable that receives the number of bytes actually returned to Buffer if the 
call was successful, or the number of bytes needed to contain the available data if the 
call fails with STATUS_BUFFER_TOO_SMALL. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_OBJECT_NAME_NOT_FOUND, STATUS_KEY_DELETED, or 
STATUS BUFFER TOO SMALL. 
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Related Win32 Functions 

RegQueryMultipleValues. 

Remarks 

None. 



KFY VALUF ENTRY 



typedef struct _KEY_VALUE_ENTRY { 

PUNICODE_STRING ValueName; 

ULONG DataLength; 

ULONG DataOffset ; 

ULONG Type; 

} KEY_VALUE_ENTRY , *PKEY_VALUE_ENTRY ; 

Members 

ValueName 

Specifies the name of the value whose data is to be retrieved. 

DataLength 

Receives the length in bytes of the data of the value. 

DataOffset 

Receives the offset in bytes from the start of the Buffer to the value’s data. 

Type 

Receives the data type of the value. 

Remarks 

None. 



ZwInitializeRegistry 



ZwInitializeRegistry initializes the registry. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwInitializeRegistry ( 

IN BOOLEAN Setup 

); 



Parameters 

Setup 

Specifies whether the system was hooted for system setup. 







Registry Keys: ZwInitializeRegistry 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

None. 



Remarks 

The Session Manager processes (smss.exe) calls ZwInitializeRegistry to initialize the 
registry during system startup. Once the registry has been initialized, subsequent calls 
to ZwInitializeRegistry fail with STATUS_ACCESS_DENIED. 
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15 

Security and Auditing 



The system services described in this chapter are used to implement access checks and 
auditing for private objects. 



ZwPrivilegeCheck 



ZwPrivilegeCheck checks whether a set of privileges are enabled in a token. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPrivilegeCheck ( 

IN HANDLE TokenHandle, 

IN PPRIVILEGE_SET RequiredPrivileges , 

OUT PBOOLEAN Result 

); 



Parameters 

TokenHandle 

A handle to a token object. The handle must grant TOKEN_QUERY access. 
RequiredPrivileges 

Points to a structure specifying the privileges required. 

Result 

Points to a variable that receives the result of the privilege check. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 
STATUS_INVALID_HANDLE, or STATUS_BAD_IMPERSONATION_LEVEL. 

Related Win32 Functions 

PrivilegeCheck. 

Remarks 

PrivilegeCheck exposes the full functionality of ZwPrivilegeCheck. 
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ZwPrivilegeObjectAuditAlarm 



ZwPrivilegeObjectAuditAlarm generates an audit alarm describing the use of privi- 
leges in conjunction with a handle to an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPrivilegeObjectAuditAlarm( 

IN PUNIC0DE_STRING SubsystemName , 

IN PVOID Handleld, 

IN HANDLE TokenHandle, 

IN ACCESS_MASK DesiredAccess , 

IN PPRIVILEGE_SET Privileges, 

IN BOOLEAN AccessGranted 

); 



Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

A value representing the client’s handle to the object. If the access is denied, this 
parameter is ignored. 

TokenHandle 

A handle to the token object representing the client requesting the operation. 

The handle must grant TOKEN_QUERY access. 

DesiredAccess 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

Privileges 

Points to a PRIVILEGE_SET structure that specifies the set of privileges required for the 
access. 

AccessGranted 

Points to a variable that receives an indication of whether access was granted or 
denied. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD. 
STATUS_BAD_IMPERSONATION_LEVEL, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

Ob j ectPrivilegeAuditAlarm. 
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Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

Obj ectPrivilegeAuditAlarm exposes the full functionality of 

ZwPrivilegeObjectAudit Alarm. 



ZwPrivilegedServiceAuditAlarm 



ZwPrivilegedServiceAuditAlarm generates an audit alarm describing the use of 
privileges. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPrivilegedServiceAuditAlarm ( 

IN PUNIC0DE_STRING SubsystemName , 

IN PUNICODE_STRING ServiceName, 

IN HANDLE TokenHandle, 

IN PPRIVILEGE_SET Privileges, 

IN BOOLEAN AccessGranted 

); 




Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

ServiceName 

Points to a string specifying the name of the service to which the client gained access 
or attempted to gain access. 

TokenHandle 

A handle to the token object representing the client requesting the operation. 

The handle must grant TOKEN_QUERY access. 

Privileges 

Points to a PRIVILEGE_SET structure that specifies the set of privileges required for the 
access. 

AccessGranted 

Points to a variable that receives an indication of whether access was granted or 
denied. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD , or 
STATUS_BAD IMPERSONATION_LEVEL. 

Related Win32 Functions 

PrivilegedServiceAud it Alarm. 
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Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

PrivilegedServiceAuditAlarm exposes the full functionality of 

ZwPrivilegedServiceAudit Alarm. 



ZwAccessCheck 



ZwAccessCheck checks whether a security descriptor grants the requested access to an 
agent represented by a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheck ( 

IN PSECURITY_DESCRIPTOR SecurityDescriptor, 

IN HANDLE TokenHandle, 

IN ACCESS_MASK DesiredAccess , 

IN PGENERIC_MAPPING GenericMapping , 

IN PPRIVILEGE_SET PrivilegeSet , 

IN PULONG PrivilegeSetLength, 

OUT PACCESS_MASK GrantedAccess , 

OUT PBOOLEAN AccessStatus 

); 



Parameters 

SecurityDescriptor 

Points to a SECURITY_DESCRIPTOR structure against which access is checked. 

TokenHandle 

A handle to the token object representing the client requesting the operation. 

The handle must grant TOKEN_QUERY access. 

DesiredAccess 

Specifies the access mask to be requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

PrivilegeSet 

Points to a PRIVILEGE_SET structure that the function fills with any privileges used to 
perform the access validation. 

PrivilegeSetLength 

Specifies the size, in bytes, of PrivilegeSet. 

GrantedAccess 

Points to a variable that receives the granted access mask. 
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AccessStatus 

Points to a variable that receives the result of the access check. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_BUFFER_TOO_SMALL, 
STATUS_NO_IMPERSONATION_TOKEN, STATUS_INVALID_SECURITY_DESCR, 
STATUS_BAD_IMPERSONATION_LEVEL, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheck. 

Remarks 

AccessCheck exposes the full functionality of ZwAccessCheck. 



ZwAccessCheckAndAuditAlarm 



ZwAccessCheckAndAuditAlarm checks whether a security descriptor grants the 
requested access to an agent represented by the impersonation token of the current 
thread. If the security descriptor has a SACL with ACEs that apply to the agent, any 
necessary audit messages are generated. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheckAndAuditAlarm ( 

IN PUNICODE_STRING SubsystemName , 

IN PVOID Handleld, 

IN PUNICODE_STRING Ob j ectTypeName , 

IN PUNIC0DE_STRING ObjectName, 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN ACCESS_MASK DesiredAccess , 

IN PGENERIC_MAPPING GenericMapping , 

IN BOOLEAN Ob j ectCreation , 

OUT PACCESS_MASK GrantedAccess , 

OUT PBOOLEAN AccessStatus, 

OUT PBOOLEAN GenerateOnClose 

); 

Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

A value representing the client’s handle to the object. If the access is denied, this 
parameter is ignored. 

Obj ectTypeName 

Points to a string specifying the type of object to which the client is requesting access. 
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ObjectName 

Points to a string specifying the name of the object to which the client gained access 
or attempted to gain access. 

Secu ri ty Descrip to r 

Points to the SECURITY_DESCRIPTOR structure for the object being accessed. 

DesiredAccess 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

ObjectCreation 

Specifies whether a new object will be created or an existing object will be opened. 

GrantedAccess 

Points to a variable that receives the access granted. 

AccessStatus 

Points to a variable that receives an indication of whether access was granted or 
denied. 

GenerateOnClose 

Points to a variable that receives an indication of whether an audit alarm should be 
generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_INVALID_SECURITY_DESCR, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckAndAudit Alarm. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

AccessCheckAndAuditAlarm exposes the full functionality of 

ZwAecessCheckAndAuditAlarm. 




Security and Auditing: ZwAeeessCheckByType 



ZwAeeessCheckByType 



ZwAeeessCheckByType checks whether a security descriptor grants the requested access 
to an agent represented by a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAeeessCheckByType ( 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN PSID PrincipalSelfSid, 

IN HANDLE TokenHandle, 

IN ULONG DesiredAccess, 

IN POBJECT_TYPE_LIST Ob j ectTypeList , 

IN ULONG ObjectTypeListLength, 

IN PGENERIC_MAPPING GenericMapping , 

IN PPRIVILEGE_SET PrivilegeSet , 

IN PULONG PrivilegeSetLength, 

OUT PACCESS_MASK GrantedAccess , 

OUT PULONG AccessStatus 

); 



Parameters 

Secu ri ty Descrip to r 

Points to a SECURITY_DESCRIPTOR structure against which access is checked. 

PrincipalSelfSid 

Points to a SID that is used to replace any occurrence in SecurityDescriptor of the 
well-known SID PRINCIPAL_SELF. 

TokenHandle 

A handle to the token object representing the client requesting the operation. The 
handle must grant TOKEN_QUERY access. 

DesiredAccess 

Specifies the access mask to be requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

Obj ectTypeList 

Points to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object 
types for which to check access. 

Object TypeListLength 

The number of elements in the Obj ectTypeList array. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

PrivilegeSet 

Points to a PRIVILEGE_SET structure that the function fills with any privileges used to 
perform the access validation. 
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Privilege SetLength 

Specifies the size, in bytes, of PrivilegeSet. 
GrantedAccess 

Points to a variable that receives the granted access mask. 



AccessStatus 

Points to a variable that receives the result of the access check. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_BUFFER_TOO_SMALL, 
STATUS_NO_IMPERSONATION_TOKEN, STATUS_INVALID_SECURITY_DESCR, 
STATUS_BAD_IMPERSONATION_LEVEL, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckByType. 

Remarks 

AccessCheckByType exposes the full functionality of ZwAccessCheckByType. 
The routine ZwAccessCheckByType is only present in Windows 2000. 



ZwAccessCheckByTypeAndAuditAlarm 



ZwAccessCheckByTypeAndAuditAlarm checks whether a security descriptor grants the 
requested access to an agent represented by the impersonation token of the current 
thread. If the security descriptor has a SACL with ACEs that apply to the agent, any 
necessary audit messages are generated. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheckByTypeAndAuditAlarm( 

IN PUNICODE_STRING SubsystemName , 

IN PVOID Handleld, 

IN PUNICODE_STRING Ob j ectTypeName , 

IN PUNICODE_STRING ObjectName, 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN PSID PrincipalSelfSid, 

IN ACCESS_MASK DesiredAccess , 

IN AUDIT_EVENT_TYPE AuditType, 

IN ULONG Flags, 

IN POBJECT_TYPE_LIST Ob j ectTypeList , 

IN ULONG ObjectTypeListLength, 

IN PGENERIC_MAPPING GenericMapping , 

IN BOOLEAN Ob j ectCreation , 

OUT PACCESS_MASK GrantedAccess, 

OUT PULONG AccessStatus, 

OUT PB00LEAN GenerateOnClose 

); 
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Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

A value representing the client’s handle to the object. If the access is denied, this 
parameter is ignored. 

ObjectTypeName 

Points to a string specifying the type of object to which the client is requesting access. 

ObjectName 

Points to a string specifying the name of the object to which the client gained access 
or attempted to gain access. 

Secu ri ty Descrip tor 

Points to the SECURITY_DESCRIPTOR structure for the object being accessed. 

PrincipalSelfSid 

Points to a SID that is used to replace any occurrence in SecurityDescriptor of the 
well-known SID PRINCIPAL_SELF. 

DesiredAccess 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

AuditType 

Specifies the type of audit to be generated. Permitted values are drawn from the 
enumeration AUDIT_EVENT_TYPE. 

typedef enum _AUDIT_EVENT_TYPE { 

AuditEventOb j ectAccess , 

Audit EventDirectoryServiceAccess 
} AUDIT_EVENT_TYPE , *PAUDIT_EVENT_TYPE; 




A bit array of flags that affect the behavior of the routine. The following flags are 
defined: 

AUDIT_ALLOW_NO_PRIVILEGE 

ObjectTypeList 

Points to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object 
types for which to check access. 

Object TypeListLength 

The number of elements in the ObjectTypeList array. 



GenericMapping 
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Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

ObjectCreation 

Specifies whether a new object will be created or an existing object will be opened. 

GrantedAccess 

Points to a variable that receives the access granted. 

Access Status 

Points to a variable that receives an indication of whether access was granted or 
denied. 

Generate OnClose 

Points to a variable that receives an indication of whether an audit alarm should be 
generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_INVALID_SECURITY_DESCR, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckByTypeAndAudit Alarm. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

AccessCheckByTypeAndAuditAlarm exposes the full functionality of 

ZwAccessCheckByTypeAndAudit Alarm. 

The routine ZwAccessCheckByTypeAndAudit Alarm is only present in Windows 2000. 



ZwAccessCheckByTypeResultList 



ZwAccessCheckByTypeResultList checks whether a security descriptor grants the 
requested access to an agent represented by a token object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheckByTypeResultList ( 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN PSID PrincipalSelfSid, 

IN HANDLE TokenHandle, 

IN ACCESS_MASK DesiredAccess , 

IN POBJECT_TYPE_LIST Obj ectTypeList , 

IN ULONG ObjectTypeListLength, 

IN PGENERIC_MAPPING GenericMapping , 

IN PPRIVILEGE_SET PrivilegeSet , 

IN PULONG PrivilegeSetLength, 
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OUT PACCESS_MASK GrantedAccessList , 
OUT PULONG AccessStatusList 
); 




Parameters 

Secu ri ty Descrip to r 

Points to a SECURITY_DESCRIPTOR structure against which access is checked. 

Principal Self Sid 

Points to a SID that is used to replace any occurrence in SecurityDescriptor of the 
well-known SID PRINCIPAL_SELF. 

TokenHandle 

A handle to the token object representing the client requesting the operation. The 
handle must grant TOKEN_QUERY access. 

DesiredAccess 

Specifies the access mask to be requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

ObjectTypeList 

Points to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object 
types for which to check access. 

Object TypeListLength 

The number of elements in the ObjectTypeList array. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

PrivilegeSet 

Points to a PRIVILEGE_SET structure that the function fills with any privileges used to 
perform the access validation. 

Privilege SetLength 

Specifies the size, in bytes, of PrivilegeSet. 

GrantedAccessList 

Points to a caller- allocated buffer or variable that receives an array of granted access 
masks, one per element in the ObjectTypeList. 

AccessStatusList 

Points to a caller- allocated buffer or variable that receives an array of the results of the 
access check, one per element in the ObjectTypeList. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
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STATUS_INVALID_HANDLE, STATUS_BUFFER_TOO_SMALL, 
STATUS_NO_IMPERSONATION_TOKEN, STATUS_INVALID_SECURITY_DESCR, 
STATUS_BAD_IMPERSONATION_LEVEL or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckByTypeResultList. 

Remarks 

AccessCheckByTypeResultList exposes the full functionality of 

ZwAceessCheekByTypeResultList. 

The routine ZwAceessCheekByTypeResultList is only present in Windows 2000. 



ZwAccessCheckByTypeResultListAndAuditAlarm 



ZwAccessCheckByTypeResultListAndAuditAlarm checks whether a security descriptor 
grants the requested access to an agent represented by the impersonation token of the 
current thread. If the security descriptor has a SACL with ACEs that apply to the 
agent, any necessary audit messages are generated. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheckByTypeResultListAndAuditAlarm( 

IN PUNICODE_STRING SubsystemName , 

IN PVOID Handleld, 

IN PUNICODE_STRING Ob j ectTypeName , 

IN PUNIC0DE_STRING ObjectName, 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN PSID PrincipalSelfSid , 

IN ACCESS_MASK DesiredAccess , 

IN AUDIT_EVENT_TYPE AuditType, 

IN ULONG Flags, 

IN POBJECT_TYPE_LIST Ob j ectTypeList , 

IN ULONG ObjectTypeListLength, 

IN PGENERIC_MAPPING GenericMapping , 

IN BOOLEAN Ob j ectCreation , 

OUT PACCESS_MASK GrantedAccessList , 

OUT PULONG AccessStatusList, 

OUT PULONG GenerateOnClose 

); 



Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

A value representing the client’s handle to the object. If the access is denied, this 
parameter is ignored. 

Object TypeName 

Points to a string specifying the type of object to which the client is requesting access. 
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ObjectName 

Points to a string specifying the name of the object to which the client gained access 
or attempted to gain access. 

Secu ri ty Descrip to r 

Points to the SECURITY_DESCRIPTOR structure for the object being accessed. 

Principal Self Sid 

Points to a SID that is used to replace any occurrence in SecurityDescriptor of the 
well-known SID PRINCIPAL_SELF. 

Desired Access 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

AuditType 

Specifies the type of audit to be generated. Permitted values are drawn from the 
enumeration AUDIT_EVENT_TYPE. 

typedef enum _AUDIT_EVENT_TYPE { 

AuditEventOb j ectAccess , 

AuditEventDirectoryServiceAccess 
} AUDIT_EVENT_TYPE , *PAUDIT_EVENT_TYPE; 



A bit array of flags that affect the behavior of the routine. The following flags are 
defined: 

AUDIT_ALLOW_NO_PRIVILEGE 

ObjectTypeList 

Points to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object 
types for which to check access. 

Object TypeListLength 

The number of elements in the ObjectTypeList array. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 

ObjectCreation 

Specifies whether a new object will be created or an existing object will be opened. 

QrantedAccessList 

Points to a caller- allocated buffer or variable that receives an array of granted access 
masks, one per element in the ObjectTypeList. 

Access StatusList 

Points to a caller-allocated buffer or variable that receives an array of the results of the 
access check, one per element in the ObjectTypeList. 
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GenerateOnClose 

Points to a variable that receives an indication of whether an audit alarm should be 
generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_INVALID_SECURITY_DESCR, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckByTypeResult List AndAud it Alarm. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

AccessCheckByTypeResultListAndAuditAlarm exposes the full functionality of 

ZwAccessCheckByTypeResultListAndAuditAlarm. 

The routine ZwAccessCheckByTypeResultListAndAuditAlarm is only present in 
Windows 2000. 



ZwAccessCheckByTypeResultListAndAuditAlarmByHandle 



ZwAccessCheckByTypeResultListAndAuditAlarmByHandle checks whether a security 
descriptor grants the requested access to an agent represented by a token. If the security 
descriptor has a SACL with ACEs that apply to the agent, any necessary audit messages 
are generated. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAccessCheckByTypeResultListAndAuditAlarmByHandle( 

IN PUNIC0DE_STRING SubsystemName , 

IN PVOID Handleld, 

IN HANDLE TokenHandle, 

IN PUNICODE_STRING Ob j ectTypeName , 

IN PUNIC0DE_STRING ObjectName, 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN PSID PrincipalSelfSid, 

IN ACCESS_MASK DesiredAccess , 

IN AUDIT_EVENT_TYPE AuditType, 

IN ULONG Flags, 

IN POBJECT_TYPE_LIST Ob j ectTypeList , 

IN ULONG ObjectTypeListLength, 

IN PGENERIC_MAPPING GenericMapping , 

IN BOOLEAN Ob j ectCreation , 

OUT PACCESS_MASK GrantedAccessList , 

OUT PULONG AccessStatusList, 

OUT PULONG GenerateOnClose 

); 




Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 
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Handleld 

A value representing the client’s handle to the object. If the access is denied, this 
parameter is ignored. 

TokenHandle 

A handle to a token object representing the client. The handle must grant 
TOKEN_QUERY access. 

ObjectTypeName 

Points to a string specifying the type of object to which the client is requesting access. 

ObjectName 

Points to a string specifying the name of the object to which the client gained access 
or attempted to gain access. 

Secu ri ty Descrip to r 

Points to the SECURITY_DESCRIPTOR structure for the object being accessed. 

PrincipalSelfSid 

Points to a SID that is used to replace any occurrence in SecurityDescriptor of the 
well-known SID PRINCIPAL_SELF. 

DesiredAccess 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

AuditType 

Specifies the type of audit to be generated. Permitted values are drawn from the 
enumeration AUDIT_EVENT_TYPE. 

typedef enum _AUDIT_EVENT_TYPE { 

AuditEventOb j ectAccess , 

AuditEventDirectoryServiceAccess 
} AUDIT_EVENT_TYPE , *PAUDIT_EVENT_TYPE; 



A bit array of flags that affect the behavior of the routine. The following flags are 
defined: 

AUDIT_ALLOW_NO_PRIVILEGE 

ObjectTypeList 

Points to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object 
types for which to check access. 

Object TypeListLength 

The number of elements in the ObjectTypeList array. 

GenericMapping 

Points to the GENERIC_MAPPING structure associated with the object for which access is 
being checked. 
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ObjectCreation 

Specifies whether a new object will be created or an existing object will be opened. 

GrantedAccessList 

Points to a caller-allocated buffer or variable that receives an array of granted access 
masks, one per element in the Obj ectTypeList. 

AccessStatusList 

Points to a caller-allocated buffer or variable that receives an array of the results of the 
access check, one per element in the Obj ectTypeList. 

Generate On Close 

Points to a variable that receives an indication of whether an audit alarm should be 
generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_INVALID_SECURITY_DESCR, or STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

AccessCheckByTypeRes ult List AndAud it AlarmByHandle. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

AccessCheckByTypeResultListAndAuditAlarmByHandle exposes the full functionality 

of ZwAccessCheckByTypeResult Lis tAndAudit AlarmByHandle. 

The routine ZwAccessCheckByTypeResultListAndAuditAlarmByHandle is only present 
in Windows 2000. 




ZwOpenObjectAuditAlarm 



ZwOpenObjectAuditAlarm generates an audit alarm describing the opening of a handle 
to an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwOpenObjectAuditAlarm ( 

IN PUNICODE_STRING SubsystemName , 

IN PVOID *HandleId, 

IN PUNICODE_STRING Ob j ectTypeName , 

IN PUNIC0DE_STRING ObjectName, 

IN PSECURITY_DESCRIPTOR SecurityDescriptor , 

IN HANDLE TokenHandle, 

IN ACCESS_MASK DesiredAccess , 

IN ACCESS_MASK GrantedAccess , 

IN PPRIVILEGE_SET Privileges OPTIONAL, 

IN BOOLEAN ObjectCreation, 

IN BOOLEAN AccessGranted , 

OUT PB00LEAN GenerateOnClose 

); 
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Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

Points to a value representing the client’s handle to the object. If the access is denied, 
this parameter is ignored. 

ObjectTypeName 

Points to a string specifying the type of object to which the client is requesting access. 

ObjectName 

Points to a string specifying the name of the object to which the client gained access 
or attempted to gain access. 

Seen ri ty Descrip tor 

Points to the SECURITY_DESCRIPTOR structure for the object being accessed. 

TokenHandle 

A handle to the token object representing the client requesting the operation. The 
handle must grant TOKEN_QUERY access. 



DesiredAccess 

Specifies the access requested. This mask must have been mapped by the 
MapGenericMask or RtlMapGenericMask function to contain no generic access rights. 

GrantedAccess 

Specifies the access granted. 

Privileges 

Optionally points to a PRIVILEGE_SET structure that specifies the set of privileges 
required for the access. This parameter can be a null pointer. 

ObjectCreation 

Specifies whether a new object was created or an existing object was opened. 

Access Granted 

Specifies whether access was granted or denied. 

Generate On Close 

Points to a variable that receives an indication of whether an audit alarm should be 
generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_PRIVILEGE_NOT_HELD, 
STATUS_INVALID_SECURITY_DESCR, STATUS_BAD_IMPERSONATION_LEVEL or 
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STATUS_GENERIC_NOT_MAPPED. 

Related Win32 Functions 

Ob j ectOpenAuditAlarm. 

Remarks 

SeAuditPnvilege is required to generate an audit alarm. 

Ob j ectOpenAuditAlarm exposes the full functionality of ZwOpenObjectAuditAlarm. 



ZwCloseObjectAuditAlarm 



ZwCloseObjectAuditAlarm generates an audit alarm describing the closing of a handle 
to an object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCloseOb j ectAuditAlarm ( 

IN PUNIC0DE_STRING SubsystemName , 

IN PVOID Handleld, 

IN BOOLEAN GenerateOnClose 

); 



Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

Specifies a value representing the clients handle to the object. 

GenerateOnClose 

Specifies whether an audit alarm should be generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status... such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

Ob j ectCloseAuditAlarm. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

Ob j ectCloseAuditAlarm exposes the full functionality of ZwCloseObjectAuditAlarm. 
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ZwDeleteObjectAuditAlarm 



ZwDeleteObjectAuditAlarm generates an audit alarm describing the deletion of an 
object. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeleteObjectAuditAlarm ( 

IN PUNIC0DE_STRING SubsystemName , 

IN PVOID Handleld, 

IN BOOLEAN GenerateOnClose 

); 




Parameters 

SubsystemName 

Points to a name identifying the subsystem generating the audit alarm. 

Handleld 

Specifies a value representing the clients handle to the object. 

GenerateOnClose 

Specifies whether an audit alarm should be generated when the handle is closed. 

Return Value 

Returns STATUS_SUCCESS or an error status... such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

Ob j ectDeleteAuditAlarm. 

Remarks 

SeAuditPrivilege is required to generate an audit alarm. 

Ob j ectDeleteAuditAlarm exposes the full functionality of 

ZwDeleteObjectAuditAlarm. 
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Plug and Play and 
Power Management 



The system services described in this chapter support plug and play and power 
management. 



ZwRequestWakeupLatency 



ZwRequestWakeupLatency controls the speed with which the system should be able to 
enter the working state. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRequestWakeupLatency ( 

in latency_time Latency 

); 



Parameters 

Latency 

Specifies the desired latency requirement. The permitted values are drawn from the 
enumeration LATENCY_TIME: 

typedef enum { 

LT_DONT_CARE , 

LT_LOWEST_LATENCY 
} LATENCY_TIME; 

Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

RequestWakeupLatency. 

Remarks 

RequestWakeupLatency exposes the full functionality of ZwRequestWakeupLatency. 
The routine ZwRequestWakeupLatency is only present in Windows 2000. 
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ZwRequestDeviceWakeup 



ZwRequestDeviceWakeup issues a wakeup request to a device. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRequestDeviceWakeup ( 

IN handle DeviceHandle 

); 



Parameters 

DeviceHandle 

A handle to a file object representing a device. The handle need not grant any specific 
access. 

Return Value 

Returns STATUS_SUCCESS or an error status, ZwRequestDeviceWakeup such as 
STATUS_INVALID_HANDLE or STATUS_NOT_IMPLEMENTED. 

Related Win32 Functions 

RequestDeviceWakeup. 

Remarks 

RequestDeviceWakeup exposes the full functionality of ZwRequestDeviceWakeup. 

The routine ZwRequestDeviceWakeup is only present in Windows 2000. 

Device wakeup requests are not implemented in early versions of Windows 2000. 



ZwCancelDeviceWakeupRequest 



ZwCancelDeviceWakeupRequest cancels a previously issued device wakeup request. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCancelDeviceWakeupRequest ( 

IN HANDLE DeviceHandle 

); 



Parameters 

DeviceHandle 

A handle to a file object representing a device. The handle need not grant any specific 
access. 



Return Value 
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Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE or 
STATUS_NOT_IMPLEMENTED. 

Related Win32 Functions 

CancelDeviceWakeupRequest. 

Remarks 

CancelDeviceWakeupRequest exposes the full functionality of 

ZwCancelDeviceWakeupRequest. 

The routine ZwCancelDeviceWakeupRequest is only present in Windows 2000. 

Device wakeup requests are not implemented in early versions of Windows 2000. 



ZwIsSystemResumeAutomatic 



ZwIsSystemResumeAutomatic reports whether the system was resumed to handle a 
scheduled event or was resumed in response to user activity. 

NTSYSAPI 

BOOLEAN 

NTAPI 

ZwIsSystemResumeAutomatic ( 

VOID 

); 



Parameters 

None. 

Return Value 

Returns TRUE or FALSE. 

Related Win32 Functions 

IsSystemResumeAutomatic. 

Remarks 

IsSystemResumeAutomatic exposes the full functionality of 

ZwIsSystemResumeAutomatic. 

The routine ZwIsSystemResumeAutomatic is only present in Windows 2000. 
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ZwSetThreadExecutionState 



ZwSetThreadExecutionState sets the execution requirements of the current thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetThreadExecutionState ( 

in execution_state ExecutionState , 

OUT PEXECUTI0N_STATE PreviousExecutionState 

); 



Parameters 

ExecutionState 

Specifies the execution requirements of the current thread. The permitted values are 
any combination oi the following flags: 

ES_SYSTEM_REQUIRED 
ES_DISPLAY_REQUIRED 
ES CONTINUOUS 



PreviousExecutionState 

Points to a variable that receives the previous execution requirements of the current 
thread. The value returned is zero or a combination of the following flags: 

ES_SYSTEM_REQUIRED 
ES_DISPLAY_REQUIRED 
ES_USER_PRESENT 
ES CONTINUOUS 



Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

SetThreadExecutionState. 



Remarks 

SetThreadExecutionState exposes the full functionality of 

ZwSetThreadExecutionState. 

The routine ZwSetThreadExecutionState is only present in Windows 2000. 



ZwGetDevicePowerState 



ZwGetDevicePowerState retrieves the power state of a device. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwGetDevicePowerState ( 

IN HANDLE DeviceHandle , 
out pdevice_power_state DevicePowerState 
); 
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Parameters 

DeviceHandle 

A handle to a file object representing a device. The handle need not grant any specific 
access. 

DevicePowerState 

Points to a variable that receives the power state of the device. The values are drawn 
from the enumeration DEVICE_POWER_STATE: 

typedef enum _DEVICE_POWER_STATE { 

PowerDeviceUnspecified = 0, 

PowerDeviceD0, 

PowerDeviceDI , 

PowerDeviceD2, 

PowerDeviceD3 

} DEVICE_POWER_STATE, *PDEVICE_POWER_STATE; 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_I NVALI D_HANDLE . 



Related Win32 Functions 

GetDevicePowe estate. 

Remarks 

GetDevicePowenState exposes most of the functionality of ZwGetDevicePowerState. 
The routine ZwGetDevicePowerState is only present in Windows 2000. 



ZwSetSystemPowerState 



ZwSetSystemPowerState sets the power state of the system. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetSystemPowerState ( 

in power_action SystemAction , 

IN system_power_state MinSystemState , 

IN ULONG Flags 

); 



Parameters 

SystemAction 

Specifies the power action to perform. The permitted values are drawn from the 
enumeration P0WER_ACTI0N: 

typedef enum _P0WER_ ACTION { 

PowerActionNone, 

PowerActionReserved , 

PowerActionSleep, 

PowerActionHibernate , 

PowerActionShutdown , 
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PowerActionShutdownReset , 

PowerActionShutdownOff 

} P0WER_ACTI0N, *PP0WER_ACTI0N; 

MinSystemState 

Specifies the minimum power state to enter as a result oi performing the action. 

The permitted values are drawn from the enumeration SYSTEM_POWER_STATE: 

typedef enum _SYSTEM_POWER_STATE { 

PowerSystemUnspecified = 0, 

PowerSystemWorking , 

PowerSystemSleepingl , 

PowerSystemSleeping2, 

PowerSystemSleeping3, 

PowerSystemHibernate, 

PowerSystemShutdown 

} SYSTEM_POWER_STATE, *PSYSTEM_POWER_STATE; 



Flags 

Qualifies the SystemAction. Defined values include: 

POWER_ACTION_QUERY_ALLOWED 

POWER_ACTION_UI_ALLOWED 

POWER_ACTION_OVERRIDE_APPS 

P0WER_ACTI0N_L0CK_C0NS0LE 

POWER_ACTION_DISABLE_WAKES 

POWER ACTION CRITICAL 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_ALREADY_COMMITTED, or STATUS_CANCELLED. 



Related Win32 Functions 

None. 



Remarks 

The routine ZwSetSystemPowerState is only present in Windows 2000. 
SeShutdownPrivilege is required to set the system power state. 



ZwInitiatePowerAction 



ZwInitiatePowerAction initiates a power action. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwInitiatePowerAction ( 

in power_action SystemAction, 

IN system_power_state MinSystemState, 

IN ULONG Flags, 
in boolean Asynchronous 
); 



Parameters 
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SystemAction 

Specifies the power action to perform. The permitted values are drawn from the 

enumeration P0WER_ACTI0N: 

typedef enum _POWER_ACTION { 

PowerActionNone, 

PowerActionReserved , 

PowerActionSleep, 

PowerActionHibernate , 

PowerActionShutdown , 

PowerActionShutdownReset , 

PowerActionShutdownOff 

} P0WER_ACTI0N, *PP0WER_ACTI0N; 

MinSystemState 

Specifies the minimum power state to enter as a result of performing the action. 

The permitted values are drawn from the enumeration SYSTEM_POWER_STATE: 

typedef enum _SYSTEM_POWER_STATE { 

PowerSystemUnspecified = 0, 

PowerSystemWorking , 

PowerSystemSleepingl , 

PowerSystemSleeping2, 

PowerSystemSleeping3, 

PowerSystemHibernate , 

PowerSystemShutdown 

} SYSTEM_POWER_STATE, *PSYSTEM_POWER_STATE; 



Flags 

Qualifies the SystemAction. Defined values include: 

POWER_ACTION_QUERY_ALLOWED 

POWER_ACTION_UI_ALLOWED 

POWER_ACTION_OVERRIDE_APPS 

P0WER_ACTI0N_L0CK_C0NS0LE 

POWER_ACTION_DISABLE_WAKES 

POWER ACTION CRITICAL 



Asynchronous 

Specifies whether the routine should return immediately. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 



Related Win32 Functions 

None. 



Remarks 

The routine ZwInitiatePowerAction is only present in Windows 2000. 
SeShutdownPrivilege is required to initiate a power action. 
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ZwPowerlnformation 



ZwPowerlnformation sets or queries power information. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPowerlnformation ( 

IN POWERINFORMATIONLEVEL Powerlnf ormationLevel , 

IN PVOID InputBuffer OPTIONAL, 

IN ULONG InputBufferLength, 

OUT PVOID OutputBuffer OPTIONAL, 

IN ULONG OutputBufferLength 

); 

Parameters 

Powerlnf ormationLevel 

The code for the information level to be queried or set. Permitted values are drawn 
from the enumeration POWER_INFORMATION_LEVEL, described in the following section. 

InputBuffer 

Points to a caller-allocated buffer or variable that contains the data required to perform 
the operation. This parameter can be null if the Powerlnf ormationLevel parameter 
specifies a level that does not require input data. 

InputBufferLength 

The size in bytes of InputBuffer. 

OutputBuffer 

Points to a caller-allocated buffer or variable that receives the operation’s output data. 
This parameter can be nidi if the Powerlnf ormationLevel parameter specifies a level 
that does not produce output data. 

OutputBufferLength 

The size in bytes of OutputBuffer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD or 
STATUS_BUFFER_TOO_SMALL. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwPowerlnformation is only present in Windows 2000. 

SeCreatePagef ilePrivilege is required to set the SystemReserveHiberFile. 
SeShutdownPrivilege is required to set any other settable information level. 
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POWER_INFORMATION_LEVEL 



typedef enum { 

SystemPowerPolicyAc, 
SystemPowerPolicyDc , 

Verif ySystemPolicyAc , 
Verif ySystemPolicyDc , 
SystemPowerCapabilities, 
SystemBatteryState, 
SystemPowerStateHandler, 
ProcessorStateHandler , 
SystemPowerPolicyCurrent , 
AdministratorPowerPolicy, 
SystemReserveHiberFile, 
Processor Informat ion, 

Sy st empower Informat ion 
} POWER_INFORMATION_LEVEL; 



SystemPowerPolicyAc, SystemPowerPolicyDc, 
SystemPowerPolicyCurrent 



typedef struct _SYSTEM_POWER_POLICY { 

ULONG Revision; 

P0WER_ACTI0N_P0LICY PowerButton; 

P0WER_ACTI0N_P0LICY SleepButton; 

P0WER_ACTI0N_P0LICY LidClose; 

SYSTEM_POWER_STATE LidOpenWake; 

ULONG Reservedl ; 

P0WER_ACTI0N_P0LICY Idle; 

ULONG IdleTimeout; 

UCHAR IdleSensitivity; 

UCHAR Reserved2[3] ; 

SYSTEM_POWER_STATE MinSleep; 

SYSTEM_POWER_STATE MaxSleep; 

SYSTEM_POWER_STATE ReducedLatencySleep ; 

ULONG WinLogonFlags; 

ULONG Reserved3; 

ULONG DozeS4Timeout; 

ULONG BroadcastCapacityResolution; 

SYSTEM_POWER_LEVEL DisohargePolicy[NUM_DISCHARGE_POLICIES] ; 
ULONG VideoTimeout; 

ULONG VideoReserved[4] ; 

ULONG SpindownTimeout; 

BOOLEAN OptimizeForPower; 

UCHAR FanThrottleTolerance; 

UCHAR ForcedThrottle; 

UCHAR MinThrottle; 

P0WER_ACTI0N_P0LICY OverThrottled; 

} SYSTEM_P0WER_P0L ICY , *PSYSTEM_POWER_POLICY; 



SystemPowerCapabilities 



typedef struct _SYSTEM_POWER_CAPABILITIES { 
BOOLEAN PowerButtonPresent ; 

BOOLEAN SleepButtonPresent ; 

BOOLEAN LidPresent; 

BOOLEAN SystemSI ; 

BOOLEAN SystemS2; 
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BOOLEAN SystemS3; 

BOOLEAN SystemS4; 

BOOLEAN SystemS5; 

BOOLEAN HiberFilePresent ; 

BOOLEAN FullWake; 

UCHAR Reservedl [3] ; 

BOOLEAN ThermalControl; 

BOOLEAN ProcessorThrottle; 

UCHAR ProcessorMinThrottle; 

UCHAR ProcessorThrottleScale; 

UCHAR Reserved2[4] ; 

BOOLEAN DiskSpinDown; 

UCHAR Reserved3[8] ; 

BOOLEAN SystemBatteriesPresent ; 

BOOLEAN BatteriesAreShortTerm; 

BATTERY_REPORTING_SCALE BatteryScale[3] ; 
SYSTEM_POWER_STATE AcOnLineWake ; 

SYSTEM_POWER_STATE SoftLidWake; 

SYSTEM_POWER_STATE RtcWake; 

SYSTEM_POWER_STATE MinDeviceWakeState ; 
SYSTEM_POWER_STATE Def aultLowLatencyWake ; 

} SYSTEM_POWER_CAPABILITIES, *PSYSTEM_POWER_CAPABILITIES; 



SystemBatteryState 



typedef Struct _SYSTEM_BATTERY_STATE {_ 

BOOLEAN AcOnLine; 

BOOLEAN BatteryPresent; 

BOOLEAN Charging; 

BOOLEAN Discharging; 

BOOLEAN Reserved[4]; 

ULONG MaxCapacity; 

ULONG RemainingCapacity; 

ULONG Rate; 

ULONG EstimatedTime; 

ULONG Def aultAlertl ; 

ULONG Def aultAlert2; 

} SYSTEM_BATTERY_STATE, *PSYSTEM_BATTERY_STATE ; 



SystemPowerStateHandler 



typedef Struct _POWER_STATE_HANDLER { 

P OWE R_STAT E_HAN D L E R_T Y P E Type ; 

BOOLEAN RtcWake; 

UCHAR Reserved[3]; 

PENTER_STATE_HANDLER Handler; 

PVOID Context; 

} POWER_STATE_HANDLER , *PPOWER_STATE_HANDLER; 



Processors tateHandler 



typedef struct _PROCESSOR_STATE_HANDLER { 
UCHAR ThrottleScale; 

BOOLEAN ThrottleOnldle; 
PSET_PROCESSOR_THROTTLE SetThrottle; 
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ULONG NumldleHandlers; 

PR0CESS0R_IDLE_HANDLER_INF0 IdleHandle r [ MAX_I DLE_HANDLERS ] ; 
} PR0CESS0R_STATE_HANDLER , *PPROCESSOR_STATE_HANDLER ; 



AdministratorPowerPolicy 



typedef struct _ADMINISTRAT0R_P0WER_P0LICY { 
SYSTEM_POWER_STATE MinSleep; 

SYSTEM_POWER_STATE MaxSleep; 

ULONG MinVideoTimeout; 

ULONG MaxVideoTimeout; 

ULONG MinSpindownTimeout ; 

ULONG MaxSpindownTimeout; 

} ADMINISTRATOR_POWER_POLICY, *PADMINISTRATOR_POWER_POLICY; 



Processorlnformation 



typedef Struct _PR0CESS0R_P0WER_INF0RMATI0N { 

ULONG Number; 

ULONG MaxMhz; 

ULONG CurrentMhz; 

ULONG MhzLimit; 

ULONG MaxIdleState; 

ULONG CurrentldleState; 

} PR0CESS0R_P0WER_INF0RMATI0N , *PPR0CESS0R_P0WER_INF0RMATI0N; 



SystemPowerlnformation 



typedef Struct _SYSTEM_POWER_INFORMATION { 

ULONG MaxIdlenessAllowed; 

ULONG Idleness; 

ULONG TimeRemaining; 

UCHAR CoolingMode; 

} SYSTEM_POWER_INFORMATION, *PSYSTEM_POWER_INFORMATION; 



ZwPlugPlayControl 



ZwPlugPlayControl performs a plug and play control operation. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwPlugPlayControl( 

IN ULONG ControlCode, 

IN OUT PVOID Buffer, 

IN ULONG BufferLength 

); 



Parameters 

ControlCode 

The control code for operation to be performed. 
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Buffer 

Points to a caller-allocated buffer or variable that contains the data required to perform 
the operation and receives the result of the operation. 

Length 

The size, in bytes, of the buffer pointed to by Buffer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NOT_IMPLEMENTED, 
STATUS_PRIVILEGE_NOT_HELD, STATUS_BUFFER_T00_SMALL , or 
STATUS_I N VAL I D_PARAM ETER_M I X. 

Related Win32 Functions 

None. 

Remarks 

SeTcbPrivilege is required to perform a plug and play control operation. 

Windows NT 4.0 has a version of ZwPlugPlayControl that does not require 
SeTcbPrivilege and that has an additional (optional) parameter. 



ZwGetPlugPlayEvent 



ZwGetPlugPlayEvent gets a plug and play event. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwGetPlugPlayEvent ( 

in ulong Reservedl , 
in ulong Reserved2, 
out pvoid Buffer, 
in ulong BufferLength 
); 



Parameters 

Reserved 1 

Not used. 

Reserved2 

Not used. 

Buffer 

Points to a caller-allocated buffer or variable that receives the plug and play event. The 
information return to the buffer begins with a PLUGPLAY_NOTIFICATION_HEADER struc- 
ture: 

typedef struct _PLUGPLAY_NOTIFICATION_HEADER { 

USHORT Version; 

USHORT Size; 

GUID Event; 

} PLUGPLAY_NOTIFICATION_HEADER, * P P LUGPLAY_N0T I F I CAT 1 0N_HE ADE R ; 
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BufferLength 

The size in bytes of buffer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

None. 



Remarks 

SeTcbPrivilege is required to get plug and play events. 
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This chapter describes the system services that do not appear in any other chapter. 






ZwRaiseException raises an exception. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRaiseException ( 

IN PEXCEPTION_RECORD ExceptionRecord, 

IN PCONTEXT Context, 

IN BOOLEAN SearchFrames 
); 

Parameters 

ExceptionRecord 

Points to a structure that describes the exception. 

Context 

Points to a structure that describes the execution state at the time of the exception. 

SearchFrames 

Specifies whether frame-based exception handlers should be given a chance to handle 
the exception. 

Return Value 

Returns an error status or does not return at all. 




Related Win32 Functions 

RaiseException. 
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Remarks 

If any of the pointer arguments are invalid, ZwRaiseException returns an error status; 
otherwise, the subsequent flow of control is dependent on the actions of exception 
handlers and debuggers. 

Exceptions are discussed further in Chapter 20, “Exceptions and Debugging.” 



ZwContinue 



ZwContinue resumes execution of a saved execution context. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwContinue( 

IN PCONTEXT Context, 

IN BOOLEAN TestAlert 

); 

Parameters 

Context 

Points to a structure describing the execution state that should be restored prior to 
continuing execution. 

TestAlert 

Specifies whether ZwTestAlert should be called to clear the alerted flag and to allow 
the delivery of user APCs. 

Return Value 

Returns an error status or does not return at all. 

Related Win32 Functions 

None. 

Remarks 

If any of the pointer arguments are invalid, ZwContinue returns an error status; other- 
wise, execution will continue from the execution context specified by the Context 
argument. 

Exceptions are discussed further in Chapter 20. 



ZwW32Call 



ZwW32Call calls one of a predefined set of user mode functions. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwW32Call( 

IN ULONG Routinelndex, 
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IN PVOID Argument, 

IN ULONG ArgumentLength, 

OUT PVOID ‘Result OPTIONAL, 

OUT PULONG ResultLength OPTIONAL 

); 

Parameters 

Routinelndex 

Specifies an index into an array of routines pointed to by a field in the PEB. 

Argument 

Points to a caller-allocated buffer or variable that contains data to be passed as an 
argument to the routine. This data will be copied to the user mode stack. 

A rgu men tLength 

The size, in bytes, of the data pointed to by Argument. 

Result 

Optionally points to a caller-allocated buffer or variable that receives results from the 
routine. 

ResultLength 

Optionally points to a variable that specifies the size, in bytes, of the data pointed to by 
Result and receives the size of the data actually returned. 

Return Value 

Returns an error status, such as STATUS_NOT_IMPLEMENTED, or the value returned by 
the called routine. 

Related Win32 Functions 

None. 

Remarks 

The calling thread must have initialized its Win32 state; otherwise, ZwW32Call returns 
STATUS_NOT_IMPLEMENTED. 

ZwW32Call is only present in Windows NT 4.0. 

If the process is a client of win32k.sys, ZwW32Call saves the current state (on the 
CallbackStack) and arranges that upon return to user mode; the routine 
NTDLL!_KiUserCallbackDispatcher@12 will be run with the arguments 
Routinelndex, Argument and ArgumentLength. This routine uses the Routinelndex as 
an index into a dispatch table stored in the PEB and invokes the callback routine 
found there with two arguments: Argument and ArgumentLength. 

If this routine returns, NTDLL!_KiUserCallbackDispatcher@12 invokes 
ZwCallbackReturn with a zero length result and whatever NTSTATUS value the callback 
routine returned. ZwCallbackReturn restores the state from the CallbackStack so that 
when the system service returns, it will return to its original caller. 
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Most callback routines do not return, but instead invoke ZwCallbackReturn explicitly 
so that they can return a pointer to a buffer of results to their caller (via Result and 
ResultLength). 



ZwCallbackReturn 



ZwCallbackReturn returns from a function called by ZwW32Call. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCallbackReturn ( 

IN PVOID Result OPTIONAL, 

IN ULONG ResultLength, 

IN NTSTATUS Status 

); 



Parameters 

Result 

Optionally points to a caller-allocated buffer or variable that contains the results to be 
returned to the caller of ZwW32Call. 

ResultLength 

The size, in bytes, of the data pointed to by Result. 

Status 

Specifies a status value to be returned to the caller of ZwW32Call as the return value. 

Return Value 

Returns an error status, such as STATUS_NO_CALLBACK_ACTIVE, or does not return at all. 

Related Win32 Functions 

None. 

Remarks 

If the process is a client of win32k.sys, ZwW32Call saves the current state (on the 
CallbackStack) and arranges that upon return to user mode the routine, 
NTDLL!_KiUserCallbackDispatcher@12 will be run with the arguments 
Routinelndex, Argument and ArgumentLength.This routine uses the Routinelndex as 
an index into a dispatch table stored in the PEB and invokes the callback routine 
found there with two arguments: Argument and ArgumentLength. 

If this routine returns, NTDLL!_KiUserCallbackDispatcher@12 invokes 
ZwCallbackReturn with a zero length result and whatever NTSTATUS value the callback 
routine returned. ZwCallbackReturn restores the state from the CallbackStack so that 
when the system service returns, it will return to its original caller. 
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Most callback routines do not return, but instead invoke ZwCallbackReturn explicitly 
so that they can return a pointer to a buffer of results to their caller (via Result and 
ResultLength). 



Z wS e tLow WaitHighThre ad 



ZwSetLowWaitHighThread effectively invokes ZwSetLowWaitHighEventPair on the 

event pair of the thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetLowWaitHighThread ( 

VOID 

); 



Parameters 

None. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NO_EVENT_PAIR. 

Related Win32 Functions 

None. 

Remarks 

ZwSetLowWaitHighThread is only present inWindows NT 4.0. 

Even inWindows NT 4.0 it is difficult to call ZwSetLowWaitHighThread because three 
of the four entry points purporting to refer to this system service actually invoke a 
different routine. 

NTDLL'ZwSetLowWaitHighThread, NTDLL ! NtSetLowWaitHighThread and 
NTOSKRNL! ZwSetLowWaitHighThread all execute software interrupt 0x2c 
(KiSetLowWaitHighThread), which goes through the motions of system service dis- 
patching but always returns STATUS_NO_EVENT_PAIR. 

NTOSKRNL [NtSetLowWaitHighThread is equivalent to calling 

ZwSetLowWaitHighEventPair on the event pair previously associated with the current 
thread via a call to ZwSetlnformationThread. 



ZwSetHighWaitLowThread 



ZwSetHighWaitLowThread effectively invokes ZwSetHighWaitLowEventPair on the 

event pair of the thread. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetHighWaitLowThread ( 

VOID 

); 
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Parameters 

None. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_NO_EVENT_PAIR. 

Related Win32 Functions 

None. 

Remarks 

ZwSetHighWaitLowThread is only present in Windows NT 4.0. 

Even in Windows NT 4.0 it is difficult to call ZwSetHighWaitLowThread, because three 
of the four entry points this system service actually invoke a different routine. 

NTDLL! ZwSetHighWaitLowThread, NTDLL! NtSetHighWaitLowThread and 
NTOSKRNL! ZwSetHighWaitLowThread all execute software interrupt 0x2b 
(KiCallbackReturn). 

NTOSKRNL! NtSetHighWaitLowThread is equivalent to calling 

ZwSetLowWaitHighEventPair on the event pair previously associated with the current 
thread via a call to ZwSetlnf ormationThread. 



ZwLoadDriver 



ZwLoadDriver loads a device driver. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwLoadDriver( 

IN PUNICODE_STRING DriverServiceName 

); 



Parameters 

DriverServiceName 

Specifies the registry key name where the driver configuration information is stored. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_CONFLICTING_ADDRESSES, STATUS_INVALID_IMAGE_FORMAT, 
STATUS_PROCEDURE_NOT_FOUND, STATUS_IMAGE_ALREADY_LOADED. 
STATUS_IMAGE_CHECKSUM_MISMATCH, STATUS_IMAGE_MP_UP_MISMATCH, 
STATUS_DRIVER_ORDINAL_NOT_FOUND, STATUS_DRIVER_ENTRYPOINT_NOT_FOUND, 
STATUS_DRIVER_UNABLE_TO_LOAD, or STATUS_ILL_FORMED_SERVICE_ENTRY. 





1996 App A 12/1/99 



12:32 PM 



Page 




Miscellany: ZwUnloadDriver 41 1 



Related Win32 Functions 

None. 

Remarks 

SeLoadDriverPrivilege is required to load a driver. 

The Win32 function StartService directs the Service Control Manager process to 
execute this function on behalf of the caller. 

The Service Control Manager process provides a DriverServiceName of the form 
“ \Registry\ Machine \Sy st em\CurrentControlSet\ Services \Tcpip.” 



ZwUnloadDriver 



ZwUnloadDriver unloads a device driver. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwUnloadDriver( 

IN PUNICODE_STRING DriverServiceName 

); 



Parameters 

DriverServiceName 

Specifies the registry key name where the driver configuration information is stored. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_ILL_FORMED_SERVICE_ENTRY, or STATUS_OBJECT_NAME_NOT_FOUND. 

Related Win32 Functions 

None. 

Remarks 

SeLoadDriverPrivilege is required to unload a driver. 

The Win32 function ControlService directs the Service Control Manager process to 
execute this function on behalf of the caller. 

The Service Control Manager process provides a DriverServiceName of the form 
“ \Registry\ Machine \Sy st em\CurrentControlSet\ Services \Tcpip.” 
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ZwFlushlnstructionCache 



ZwFlushlnstructionCache flushes the instruction cache of a process. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFlushlnstructionCache ( 

IN HANDLE ProcessHandle , 

IN PVOID BaseAddress OPTIONAL, 

IN ULONG FlushSize 

); 



Parameters 

ProcessHandle 

A handle to a process. The handle must grant PROCESS_VM_WRITE access. 

BaseAddress 

Optionally specifies the base of the region to be flushed. 

FlushSize 

The size of the region to be flushed if BaseAddress is not a null pointer. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

FlushlnstructionCache. 

Remarks 

None. 



ZwFlushWriteBuffer 



ZwFlushWriteBuffer flushes the write buffer. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFlushWriteBuffer ( 

VOID 

); 



Parameters 

None. 



Return Value 



Returns STATUS SUCCESS. 
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Related Win32 Functions 

None. 

Remarks 

ZwFlushWriteBuffer invokes HAL!_KeFlushWr'iteBuffer'6 1 0 which, in the default 
HAL, just returns. 



Z wQueryD efaultLo c ale 



ZwQueryDef ault Locale retrieves the default locale. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryDef ault Locale ( 

IN BOOLEAN ThreadOrSystem, 

OUT PLCID Locale 

); 



Parameters 

Thread OrSystem 

Specifies whether the thread (if true) or system (if false) locale identifier should be 
queried. 

Locale 

Points to a variable that receives the locale identifier. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwSetDefaultLocale 



ZwSetDefaultLocale sets the default locale. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSet Default Locale ( 

IN BOOLEAN ThreadOrSystem, 

IN LCID Locale 

); 
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Parameters 

Thread OrSystem 

Specifies whether the thread (if true) or system (if false) locale id should be set. 

Locale 

The locale id. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

None. 



ZwQueryDefaultUILanguage 



ZwQueryDefaultUILanguage retrieves the default user interface language identifier. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQueryDefaultUILanguage ( 

OUT PLANGID Languageld 

); 



Parameters 

Languageld 

Points to a variable that receives the language identifier. 



Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

None. 



Remarks 

The routine ZwQueryDefaultUILanguage is only present in Windows 2000. 
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Z wS e tD efaultUILangu age 



ZwSetDefaultUILanguage sets the default user interface language identifier. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetDefaultUI Language ( 

IN LANGID Languageld 

); 



Parameters 

Languageld 

The language identifier. 

Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

None. 



Remarks 

The routine ZwSetDefaultUILanguage is only present in Windows 2000. 



ZwQuerylnstallUILanguage 



ZwQuerylnstallUILanguage retrieves the installation user interface language identifier. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnstallUILanguage ( 

OUT PLANGID Languageld 

); 



Parameters 

Languageld 

Points to a variable that receives the language identifier. 



Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

None. 



Remarks 

The routine ZwQuerylnstallUILanguage is only present in Windows 2000. 



415 
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Z wAlloc ateLo c allyU niqueld 



ZwAllocateLocallyUniqueld allocates a locally unique identifier. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAllocateLocallyUniqueld ( 

OUT PLUID Luid 

); 



Parameters 

Luid 

Points to a caller-allocated buffer or variable that receives the locally unique identifier. 



Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

AllocateLocallyUniqueld. 

Remarks 

None. 



ZwAllocateUuids 



ZwAllocateUuids allocates some of the components of a universally unique identifier. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAllocateUuids ( 

OUT PLARGE_INTEGER UuidLastTimeAllocated , 

OUT PULONG UuidDeltaTime, 

OUT PULONG UuidSequenceNumber, 

OUT PUCHAR UuidSeed 

); 



Parameters 

UuidLastTimeAllocated 

Points to a variable that receives the time when a Uuid was last allocated. 

UuidDeltaTime 

Points to a variable that receives the time since a Uuid was last allocated. 

UuidSequenceNumber 

Points to a variable that receives the Uuid allocation sequence number. 
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UuidSeed 

Points to a variable that receives the six bytes of Uuid seed. 

Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

UuidCreate. 

Remarks 

The Windows NT 4.0 version of ZwAllocateUuids does not have a UuidSeed 
parameter. 



ZwSetUuidSeed 



ZwSetUuidSeed sets the universally unique identifier seed. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetUuidSeed ( 

IN PUCHAR UuidSeed 

); 



Parameters 

UuidSeed 

Points to a caller-allocated buffer or variable that contains six bytes of seed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED. 

Related Win32 Functions 

None. 

Remarks 

The routine ZwSetUuidSeed is only present in Windows 2000. 

The UuidSeed is normally the hardware address of a network interface card. 

The token of the calling thread must have an Authenticationld of SYSTEM_LUID. 



417 
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ZwRaiseHardError 



ZwRaiseHardError displays a message box containing an error message. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwRaiseHardError ( 

IN NTSTATUS Status, 

IN ULONG NumberOf Arguments, 

IN ULONG StringArgumentsMask, 

IN PULONG Arguments, 

IN HARDERR0R_RESP0NSE_0PTI0N ResponseOption , 

OUT PHARDERROR_RESPONSE Response 

); 



Parameters 

Status 

The error status that is to be raised. 

NumberOf Arguments 

The number of substitution directives in the string associated with the error status. 

StringArgumentMask 

Specifies which of the substitution directives indicate a string substitution. 

Arguments 

Points to an array of substitution values; the values are either U LONGs or 

PUNICODE_STRINGs. 

ResponseOption 

Specifies the type of the message box. Permitted values are drawn from the enumera- 
tion HARDERROR_RESPONSE_OPTION: 

typedef enum _HARDERR0R_RESP0NSE_0PTI0N { 

Opt ionAbortRetry Ignore, 

OptionOk, 

OptionOkCancel, 

OptionRetryCancel, 

OptionYesNo, 

OptionYesNoCancel , 

OptionShutdownSystem 

} HARDERR0R_RESP0NSE_0PTI0N , *PHARDERROR_RESPONSE_OPTION ; 

Response 

Points to a variable that receives the result of the user interaction with the message 

box. Possible values received are drawn from the enumeration HARDERROR_RESPONSE: 

typedef enum _HARDERROR_RESPONSE { 

ResponseReturnToCaller, 

ResponseNotHandled , 

ResponseAbort , 

ResponseCancel, 

Responselgnore, 

ResponseNo, 
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ResponseOk, 

ResponseRetry, 

ResponseVes 

} HARDERROR_RESPONSE , *PHARDERROR_RESPONSE ; 

Return Value 

Returns STATUS SUCCESS or an error status. 



Related Win32 Functions 

None. 



Remarks 

SeShutdownPrivilege is required to use the option OptionShutdownSystem. 

The information on the number and type of arguments is needed to correctly pack 
the arguments into a message to be sent to the default hard error port. The recipient of 
the message uses the Status parameter to select a format string and then inserts the 
arguments (which should match the directives in the string). 

An example of the use of ZwRaiseHardError is: 

UNICODE_STRING s = {16, 18, L" Recalled" } ; 

ULONG x, args [ ] = {0x11111111, 0x22222222, UL0NG(&s)}; 

ZwRaiseHardError (STATUS_ACCESS_VIOLATION, 3, 4, args, MB_OKCANCEL, &x); 



ZwSetDefaultHardErrorPort 



ZwSetDefaultHardErrorPort sets the default hard error port. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetDefaultHardErrorPort ( 

IN HANDLE PortHandle 



Parameters 

PortHandle 

A handle to a port. The handle need not grant any specific access. 



Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 



Related Win32 Functions 

None. 



Remarks 

SeTcbPrivilege is required to set the default hard error port. 





1996 App A 12/1/99 



12:32 PM 



Page 




420 Miscellany: ZwSetDefaultHardErrorPort 



ZwSetDef aultHardErrorPort sets the system wide port to which “Hard Error” 
messages will be sent. Normally osrss creates the hard error port. ZwRaiseHardError 
allows kernel mode components to display a message box and receive a result. 



ZwDisplayString 



ZwDisplayString displays a string. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDisplayString ( 

IN PUNICODE_STRING String 

); 



Parameters 

String 

Specifies a string to be displayed. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD. 

Related Win32 Functions 

None. 

Remarks 

SeTcbPrivilege is required to display a string. 

ZwDisplayString only displays the string if the HAL still owns the display (before the 
display driver takes ownership) or if a crash dump is in progress. 



ZwCre atePagingFile 



ZwCreatePagingFile creates a paging file. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwCreatePagingFile ( 

IN PUNICODE_STRING FileName, 

IN PULARGE_INTEGER InitialSize, 

IN PULARGE_INTEGER MaximumSize , 

IN ULONG Reserved 

); 

Parameters 

FileName 

The full path in the native NT format of the paging file to create. 
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InitialSize 

The initial size, in bytes, of the paging file. 

MaximumSize 

The maximum size, in bytes, to which the paging file may grow. 

Reserved 

Not used. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_PRIVILEGE_NOT_HELD, 
STATUS_OBJECT_NAME_IN VALID, ST ATUS_TOO_MAN Y_PAG ING_FILES, or 
STATUS_FLOPPY_VOLUME. 

Related Win32 Functions 

None. 

Remarks 

SeCreatePagef ilePrivilege is required to create a paging file. 



ZwAddAtom 



ZwAddAtom adds an atom to the global atom table. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwAddAtom ( 

IN PWSTR String, 

IN ULONG StringLength, 

OUT PUSHORT Atom 

); 



Parameters 

String 

The string to add to the global atom table. 

StringLength 

The size in bytes of the string pointed to by String. 

Atom 

Points to a variable that receives the atom. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS OBJECT NAME INVALID. 
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Related Win32 Functions 

GlobalAddAtom. 



Remarks 

The Windows NT 4.0 version of ZwAddAtom does not have a StringLength parameter. 



ZwFindAtom 



ZwFindAtom searches for an atom in the global atom table. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwFindAtom( 

IN PWSTR String, 

IN ULONG StringLength, 

OUT PUSHORT Atom 

); 



Parameters 

String 

The string to be searched for in the global atom table. 

StringLength 

The size in bytes of the string pointed to by String. 

Atom 

Points to a variable that receives the atom. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_OBJECT_NAME_IN VALID, or STATUS_OBJECT_NAME_NOT_FOUND. 

Related Win32 Functions 

GlobalFindAtom. 

Remarks 

The Windows NT 4.0 version of ZwFindAtom does not have a StringLength 
parameter. 



ZwDeleteAtom 



ZwDeleteAtom deletes an atom from the global atom table. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwDeleteAtom ( 

IN USHORT Atom 

); 
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Atom 

The atom that is to be deleted. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED or 
STATUS_INVALID_HANDLE. 

Related Win32 Functions 

GlobalDeleteAtom. 

Remarks 

None. 



ZwQuerylnformationAtom 



ZwQuerylnformationAtom retrieves information about an atom in the global atom 
table. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwQuerylnf ormationAtom ( 

IN USHORT Atom, 

IN ATOM_INFORMATION_CLASS Atomlnf ormationClass, 

OUT PVOID Atomlnf ormation, 

IN ULONG Atomlnf ormationLength, 

OUT PULONG ReturnLength OPTIONAL 

); 

Parameters 

Atom 

The atom that is to be queried. 

Atomlnf ormationClass 

Specifies the type of atom information to be queried. The permitted values are drawn 
from the enumeration ATOM_INFORMATION_CLASS, described in the following section. 

Atomlnformation 

Points to a caller-allocated buffer or variable that receives the requested atom 
information. 

AtomlnformationLength 

The size in bytes of Atomlnf ormation, which the caller should set according to the 
given Atomlnf ormationClass. 

ReturnLength 

Optionally points to a variable that receives the number of bytes actually returned to 
Atomlnformation if the call was successful. If this information is not needed, 
ReturnLength may be a null pointer. 
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Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_ACCESS_DENIED, 
STATUS_INVALID_HANDLE, STATUS_INVALID_INFO_CLASS, or 
STATUS_I N FO_L ENGTH_M I SMATCH . 

Related Win32 Functions 

GlobalGetAtomName. 

Remarks 

None. 



ATOM_INFORMATION_CLASS 



typedef enum _ATOM_INFORMATION_CLASS { 
AtomBasicInf ormation , 

AtomList Information 
} ATOM_INFORMATION_CLASS; 



AtomBasicInformation 



typedef struct _AT0M_BAS I CONFORMATION { 

USHORT Ref erenceCount ; 

USHORT Pinned; 

USHORT NameLength; 

WCHAR Name [ 1 ] ; 

} AT0M_BAS I CONFORMATION, *PATOM_BASIC_INFORMATION; 

Members 

Reference Count 

The reference count of the atom. 

Pinned 

Specifies whether the atom is pinned or not. 
NameLength 

The size, in bytes, of the atom name. 

Name 

The name of the atom. 



Remarks 

None. 
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AtomListlnformation 



typedef struct _ATOM_LIST_INFORMATION { 

ULONG NumberOf Atoms; 

ATOM Atoms [ 1 ] ; 

} AT0M_L I ST_IN FORMAT ION, *PATOM_LIST_INFORMATION ; 

Members 

NumberOfAtoms 

The number of atoms in the global atom table. 



Atoms 

An array containing all the atoms in the global atom table. 

Remarks 

None. 



ZwSetLdtEntries 



ZwSetLdtEntries sets Local Descriptor Table (LDT) entries for a Virtual DOS 
Machine (VDM). 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwSetLdtEntries( 

IN ULONG Selectorl , 

IN LDT_ENTRY LdtEntryl , 

IN ULONG Selector, 

IN LDT_ENTRY LdtEntry2 

); 



Parameters 

Selectorl 

A local segment descriptor table entry selector. 

LdtEntryl 

A local segment descriptor table entry. 

Selector2 

A local segment descriptor table entry selector. 

LdtEntry2 

A local segment descriptor table entry. 

Return Value 

Returns STATUS_SUCCESS or an error status, such as STATUS_INVALID_LDT_DESCRIPTOR. 
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Related Win32 Functions 

None. 



Remarks 

None. 



ZwV dmControl 



ZwVdmControl performs a control operation on aVDM. 

NTSYSAPI 

NTSTATUS 

NTAPI 

ZwVdmControl( 

IN ULONG ControlCode, 

IN PVOID ControlData 

); 



Parameters 

ControlCode 

The control code for operation to be performed. 

ControlData 

Pointer to a caller-allocated buffer or variable that contains the data required to 
perform the operation. 

Return Value 

Returns STATUS_SUCCESS or an error status. 

Related Win32 Functions 

None. 

Remarks 

None. 



Unimplemented System Services 



The following system services all just return STATUS_NOT_IMPLEMENTED: 

ZwCreateChannel 

ZwListenChannel 

ZwOpenChannel 

ZwReplyWaitSendChannel 

ZwSendWaitReplyChannel 

ZwSetContextChannel 
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The following system services are only present in Windows 2000 and just return 
STATUS_NOT_IMPLEMENTED on the Intel platform: 

ZwAllocateVirtualMemory64 

ZwFreeVirtualMemory64 

ZwProtectVirtualMemory64 

ZwQueryVirtualMemory64 

ZwReadVirtualMemory64 

ZwWriteVirtualMemory64 

ZwMapViewOfVlmSection 

ZwUnmapViewOfVlmSection 

ZwReadFile64 

ZwWriteFile64 
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Calling System 
Services from 
Kernel Mode 



As was stated in the Introduction, it is in principle possible to call all of the system 
services from kernel mode code running at IRQL PASSIVE_LEVEL.The documentation 
of the system services in the previous chapters is valid for kernel mode applications 
with the minor proviso that statements regarding the need for holding privileges can 
be ignored. There is, however, a practical difficulty: ntoskrnl.exe does not export all of 
the necessary entry points. 

The following ZwXxx system service entry points are exported by ntoskrnl.exe in 
Windows 2000: 



ZwAccessCheckAndAudit Alarm 

ZwAd j ustPrivilegesToken 

ZwAlertThread 

ZwAllocateVirtualMemory 

ZwCancelloFile 

ZwCancelTimer 

ZwClearEvent 

ZwClose 

ZwCloseOb j ectAuditAlarm 

ZwConnectPort 

ZwCreateDirectoryOb j ect 

ZwCreateEvent 

ZwCreateFile 

ZwCreateKey 

ZwCreateSection 

ZwCreateSymbolicLinkOb j ect 

ZwCreateTimer 

ZwDeleteFile 

ZwDeleteKey 

ZwDeleteValueKey 

ZwDeviceloControlFile 

ZwDisplayString 

ZwDuplicateObject 

ZwDuplicateToken 

ZwEnumerateKey 

ZwEnumerateValueKey 

ZwFlushlnstructionCache 

ZwFlushKey 

ZwFlushVirtualMemory 

ZwFreeVirtualMemory 

ZwFsControlFile 

ZwInitiatePowerAction 

ZwLoadDriver 

ZwLoadKey 



ZwPower Informat ion 

ZwPulseEvent 

ZwQueryDefault Locale 

ZwQueryDefaultUI Language 

ZwQueryDirectoryFile 

ZwQueryDirectoryOb j ect 

ZwQueryEaFile 

ZwQuerylnformationFile 

ZwQuerylnformationProcess 

ZwQuerylnformationToken 

ZwQuerylnstallUI Language 

ZwQueryKey 

ZwQueryObject 

ZwQuerySection 

ZwQuerySecurityObj ect 

ZwQuerySymbolicLinkOb j ect 

ZwQuerySystemlnformation 

ZwQueryValueKey 

ZwQueryVolumelnformationFile 

ZwReadFile 

ZwReplaceKey 

ZwRequestWaitReplyPort 

ZwResetEvent 

ZwRestoreKey 

ZwSaveKey 

ZwSetDefault Locale 
ZwSetDefaultUI Language 
ZwSetEaFile 
ZwSetEvent 

ZwSetlnformationFile 
ZwSetlnformationObject 
ZwSetlnformationProcess 
ZwSetlnformationThread 
ZwSetSecurityObj ect 
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ZwMakeTemporaryObject 

ZwMapViewOf Section 

ZwNotifyChangeKey 

ZwOpenDirectoryOb j ect 

ZwOpenEvent 

ZwOpenFile 

ZwOpenKey 

ZwOpenProcess 

ZwOpenProcessToken 

ZwOpenSection 

ZwOpenSymbolicLinkOb j ect 

ZwOpenThread 

ZwOpenThreadToken 

ZwOpenTimer 



ZwSetSystemlnformation 

ZwSetSystemTime 

ZwSetTimer 

ZwSetValueKey 

ZwSetVolumelnformationFile 
ZwTerminateProcess 
ZwUnloadDriver 
ZwUnloadKey 
ZwUnmapViewOf Sect ion 
ZwWaitForMultipleOb j ects 
ZwWaitForSingleOb j ect 
ZwWriteFile 
ZwYieldExecution 



The following NtXxx system service entry points are exported by ntoskrnl.exe in 
Windows 2000: 



NtAddAtom 

NtAd j ustPrivilegesToken 

NtAllocateLocallyUniqueld 

NtAllocateUuids 

NtAllocateVirtualMemory 

NtClose 

NtConnectPort 

NtCreateEvent 

NtCreateFile 

NtCreateSection 

NtDeleteAtom 

NtDeleteFile 

NtDeviceloControlFile 

NtDuplicateOb j ect 

NtDuplicateToken 

NtFindAtom 

NtFreeVirtualMemory 

NtFsControlFile 

NtLockFile 

NtMapViewOf Section 

NtNotifyChangeDirectoryFile 

NtOpenFile 

NtOpenProcess 

NtOpenProcessToken 

NtQueryDirectoryFile 



NtQueryEaFile 

NtQuerylnformationAtom 

NtQuerylnformationFile 

NtQuerylnformationProcess 

NtQuerylnformationToken 

NtQueryQuotalnformationFile 

NtQuerySecurityObj ect 

NtQuerySystemlnformation 

NtQueryVolumelnformationFile 

NtReadFile 

NtRequestPort 

NtRequestWaitReplyPort 

NtSetEaFile 

NtSetEvent 

NtSetlnformationFile 

NtSetlnformationProcess 

NtSetlnformationThread 

NtSetQuotalnformationFile 

NtSetSecurityOb j ect 

NtSetVolumelnformationFile 

NtUnlockFile 

NtVdmControl 

NtWaitForSingleOb j ect 

NtWriteFile 



If the system service is exported in the ZwXxx form, it can be used straightforwardly by 
kernel mode code. If the service is only exported in the NtXxx form, the kernel mode 
code must consider the checks performed on pointers and access to objects, as 
described in the Introduction. 



The following system services are not exported at all: 



ZwAcceptConnectPort 

ZwAccessCheck 

ZwAccessCheckByType 

ZwAccessCheckByTypeAndAuditAlarm 

ZwAccessCheckByTypeResultList 

ZwAccessCheckByTypeResultListAndAuditAlarm 

ZwAdj ustGroupsToken 

ZwAlertResumeThread 

ZwAllocatellserPhysicalPages 

ZwAllocateVirtualMemory64 

ZwAreMappedFilesTheSame 

ZwAssignProcessToJobObj ect 



ZwQuerylnformationThread 

ZwQuerylntervalProfile 

ZwQueryloCompletion 

ZwQueryMultipleValueKey 

ZwQueryMutant 

ZwQueryPerformanceCounter 

ZwQuerySemaphore 

ZwQuerySystemEnvironmentValue 

ZwQuerySystemTime 

ZwQueryTimer 

ZwQueryTimerResolution 

ZwQueryVirtualMemory 
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ZwCallbackReturn 

ZwCancelDeviceWakeupRequest 

ZwCompleteConnectPort 

ZwContinue 

ZwCreateChannel 

ZwCreateEventPair 

ZwCreateloCompletion 

ZwCreateJobObject 

ZwCreateMailslotFile 

ZwCreateMutant 

ZwCreateNamedPipeFile 

ZwCreatePagingFile 

ZwCreatePort 

ZwCreateProcess 

ZwCreateProf ile 

ZwCreateSemaphore 

ZwCreateThread 

ZwCreateToken 

ZwCreateWaitablePort 

ZwDelayExecution 

ZwDeleteOb j ectAuditAlarm 

ZwExtendSection 

ZwFilterToken 

ZwFlushBuffersFile 

ZwFlushWriteBuffer 

ZwFreeUserPhysicalPages 

ZwFreeVirtualMemory64 

ZwGetContextThread 

ZwGetDevicePowerState 

ZwGetPlugPlayEvent 

ZwGetTickCount 

ZwImpersonateAnonymousToken 

ZwImpersonateClientOfPort 

ZwImpersonateThread 

ZwInitializeRegistry 

ZwIsSystemResumeAutomatic 

ZwListenChannel 

ZwListenPort 

ZwLoadKey2 

ZwLockVirtualMemory 

ZwMapUserPhysicalPages 

ZwMapViewOfVlmSection 

ZwNotifyChangeMultipleKeys 

ZwOpenChannel 

ZwOpenEventPair 

ZwOpenloCompletion 

ZwOpenJobObject 

ZwOpenMutant 

ZwOpenOb j ectAuditAlarm 

ZwOpenSemaphore 

ZwPlugPlayControl 

ZwPrivilegeCheck 

ZwPrivilegeOb j ectAuditAlarm 

ZwPrivilegedServiceAuditAlarm 

ZwProtectVirtualMemory 

ZwProtectVirtualMemory64 

ZwQueryAttributesFile 

ZwQueryEvent 

ZwQueryFullAttributesFile 
ZwQuerylnf ormationJobObj ect 
ZwQuerylnformationPort 



ZwQueryVirtualMemory64 

ZwQueueApcThread 

ZwRaiseException 

ZwRaiseHardError 

ZwReadFile64 

ZwReadFileScatter 

ZwReadRequestData 

ZwReadVirtualMemory 

ZwReadVirtualMemory64 

ZwRegisterThreadTerminatePort 

ZwReleaseMutant 

ZwReleaseSemaphore 

ZwRemoveloCompletion 

ZwReplyPort 

ZwReplyWaitReceivePort 

ZwReplyWaitReceivePortEx 

ZwReplyWaitReplyPort 

ZwReplyWaitSendChannel 

ZwRequestDeviceWakeup 

ZwRequestWakeupLatency 

ZwResumeThread 

ZwSaveMergedKeys 

ZwSecu reconnect Port 

ZwSendWaitReplyChannel 

ZwSetContextChannel 

ZwSetContextThread 

ZwSetDefaultHardErrorPort 

ZwSetHighEventPair 

ZwSetHighWaitLowEventPair 

ZwSetlnf ormationJobObj ect 

ZwSetlnformationKey 

ZwSetlnformationToken 

ZwSetlntervalProf ile 

ZwSetloCompletion 

ZwSetLdtEntries 

ZwSetLowEventPair 

ZwSetLowWaitHighEventPair 

ZwSetSystemEnvironmentValue 

ZwSetSystemPowerState 

ZwSetThreadExecutionState 

ZwSetTimerResolution 

ZwSetUuidSeed 

ZwShutdownSystem 

ZwSignalAndWaitForSingleOb j ect 

ZwStartProfile 

ZwStopProf ile 

ZwSuspendThread 

ZwSystemDebugControl 

ZwTerminateJobObject 

ZwTerminateThread 

ZwTestAlert 

ZwUnlockVirtualMemory 

ZwUnmapViewOfVlmSection 

ZwWaitHighEventPair 

ZwWaitLowEventPair 

ZwWriteFile64 

ZwWriteFileGather 

ZwWriteRequestData 

ZwWriteVirtualMemory 

ZwWriteVirtualMemory64 
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For some system services, there are exported and documented kernel routines with 
broadly comparable functionality; for example, KeQueryPerf ormanceCounter could be 
used in place of ZwQueryPerf ormanceCounter. 

The internal format of some objects (events, mutants, semaphores, timers, and files) are 
defined in ntddk.h, and by combining some exported and documented object manag- 
er and kernel routines, it is possible to re-implement some system services. Example 
18.1 is a re-implementation of NtQueryEvent, stripped of parameter vahdation. 



Example B.l: Re-Implementing NtQueryEvent 



#include "ntdll.h" 

NTSTATUS 

NTAPI 

MyQueryEvent ( 

IN HANDLE EventHandle, 

IN NT: :EVENT_INFORMATION_CLASS Eventlnf ormationClass , 

OUT PVOID Eventlnf ormation, 

IN ULONG EventlnformationLength, 

OUT PULONG ResultLength OPTIONAL 

) 

{ 

if (ResultLength) *ResultLength = 0; 

if (Event Inf ormationClass != NT: : EventBasicInformation) 
return STATUS_INVALID_INFO_CLASS; 

if (EventlnformationLength != sizeof (NT: : EVENT_BASIC_INFORMATION) ) 
return STATUS_INFO_LENGTH_MISMATCH ; 

NT : : PKEVENT Event; 

NTSTATUS rv = NT: :ObReferenceObjectByHandle(EventHandle, 

EVENT_MODIFY_STATE, 

*NT : : ExEventObjectType, 

NT : : ExGetPreviousMode ( ) , 
(PVOID*)&Event , 0); 

if (NT_SUCCESS(rv) ) { 

NT: :PEVENT_BASIC_INFORMATION( Event Inf ormation) ->EventType 
= NT: : EVENT_TYPE ( Event ->Header. Type) ; 

NT: :PEVENT_BASIC_INFORMATION( Event Inf ormation) ->SignalState 
= NT: : KeReadStateEvent (Event) ; 

NT : :ObDereferenceObject( Event) ; 

if (ResultLength) *ResultLength 

= sizeof (NT: : EVENT_BASIC_INFORMATION) ; 

} 

return rv; 

} 

The origin of many common error codes can be seen in Example 18.1. 

ObRef erenceOb j ectByHandle can return the following error status codes: 
STATUS_INVALID_HANDLE if EventHandle is not a vahd handle, 

STATUS_OBJECT_TYPE_MISMATCH if EventHandle is a vahd handle but not a handle to 
an event object, and STATUS_ACCESS_DENIED if the handle does not grant 
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EVENT_MODIFY_STATE access and the previous mode is user mode. The parameter 
validation performed on the pointer PreviousState can result in STATUS_ACCESS_VIO- 
LATION or STATUS_DATATYPE_MISALIGNMENT being returned. 

The example also shows that the object manager just wraps simple data structures such 
as KEVENT to provide services such as naming, ACLs, reference counting, and quotas. 

For the remaining inaccessible system services, there is no good solution, but one pos- 
sible hack is to dynamically link to ntdll.dll, which is mapped into the address space of 
every process and exports the ZwXxx entry point for every system service. The caveat 
with this technique is that ntdll.dll is mapped copy on write, and so individual 
processes could modify the ntdll.dll code that implements the ZwXxx stubs (but this 
should not be a problem for threads running in system processes such as the system 
process) . 



Example B.2: Dynamically Binding to ntdll.dll 



#include "ntdll.h" 

PVOID FindNT ( ) 

{ 

ULONG n; 

NT : :ZwQuerySystemInformation(NT : :SystemModuleInformation, 
&n, 0, &n); 

PULONG q = PUL0NG(NT: :ExAllocatePool(NT: :PagedPool, n)); 
NT : :ZwQuerySystemInformation(NT : :SystemModuleInformation, 
q, n * sizeof *q, 0) ; 



NT: :PSYSTEM_MODULE_INFORMATION p 

= NT: :PSYSTEM_MODULE_INFORMATION(q + 1); 

PVOID ntdll = 0; 

for (ULONG i = 0; i < *q; i++) 

if (_stricmp(p[i] . ImageName + p[i] .ModuleNameOff set , 
"ntdll.dll") == 0) 
ntdll = p[i] .Base; 

NT : :ExFreePool(q) ; 
return ntdll; 



PVOID FindFunc( PVOID Base, PCSTR Name) 

{ 

P I MAG E_D0S_H E AD E R dos = PIMAGE_DOS_HEADER(Base) ; 

P I MAGE_NT_H EAD E RS nt = PIMAGE_NT_HEADERS ( PCHAR ( Base ) + dos ->e_lf anew) ; 

P I MAG E_D AT A_DIRECTORY expdir 

= nt ->OptionalHeader . DataDirectory + IMAGE_DIRECTORY_ENTRY_EXPORT ; 

ULONG size = expdir->Size; 

ULONG addr = expdir ->VirtualAddress; 

PIMAGE_EXPORT_DI RECTORY exports 

= PIMAGE_EXPORT_DIRECTORY( PCHAR (Base) + addr); 

PULONG functions = PULONG (PCHAR (Base) + exports->AddressOfFunctions) ; 
PSHORT ordinals = PSH0RT( PCHAR (Base) + exports ->AddressOfNameOrdinals) ; 
PULONG names = PULONG (PCHAR (Base) + exports ->AddressOf Names) ; 



PVOID func = 0; 
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for (ULONG i = 0; i < exports->NumberOfNames; i++) { 

ULONG ord = ordinals[i]; 

if (functions[ord] < addr j | functions[ord] >= addr + size) { 
if (strcmp(PSTR(PCHAR(Base) + names[i]), Name) == 0) 
func = PCHAR(Base) + functions[ord] ; 

} 

} 

return func; 

} 

VOID Unload (NT : :PDRIVER_OBJECT) 

{ 

} 

typedef NTSTATUS (NTAPI *NtQueryPerf ormanceCounter) (PLARGE_INTEGER, 

PLARGE_INTEGER) ; 

extern "C" 

NTSTATUS DriverEntry (NT: : PDRIVER_OBJECT DriverObject, NT: : PUNICODE_STRING) 

{ 

LARGE_INTEGER Count, Freq; 

NtQueryPerformanceCounter(FindFunc(FindNT ( ) , "ZwQueryPerformanceCounter" ) ) 
(&Count, &Freq); 

NT: :DbgPrint ( "Freq = %lx, Count = %lx\n", Freq.LowPart, Count. LowPart) ; 
if (DriverObject) DriverObject->DriverUnload = Unload; 
return DriverObject ? STATUS_SUCCESS : STATUSJJNSUCCESSFUL; 

} 

Example B.2 first uses ZwQuerySystemlnformation to obtain a list of kernel images 
(which includes ntdll.dll), and it extracts the base address of ntdll.dll from this informa- 
tion. The example then uses knowledge of the format of PE format images to locate 
the export directory and to search it for the desired entry point. 

Example B.2 can be installed as a device driver and started with ZwLoadDriver or can 
be loaded directly by ZwSetSystemlnformation. 
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Intel Platform- 
Specific Entry Points 
to Kernel Mode 



On the Intel platform, a change from user mode to kernel mode can be effected 
either by calling a routine via a “Call Gate” or by using software interrupts. 

Windows 2000 does not use call gates, but instead reimplements much of the func- 
tionality of call gates in software (such as the copying of parameters), using software 
interrupts to perform the mode change. 

The ability to successfully execute a software interrupt is controlled by the Descriptor 
Privilege Level (DPL) of the Interrupt Descriptor Table (IDT) entry. Windows 2000 
sets the DPLs on the IDT entries such that user mode code is only allowed to execute 
the following software interrupts: 

03 : _KiTrap03 (int3) 

04 : _KiTrap04 (into) 

2A : _KiGetTickCount 
2B : _KiCallbackReturn 

2C : _KiSetLowWaitHighThread 
2D : _KiDebugService 
2E : _KiSystemService 



KiTrap03 



KiTrap03 is the handler for the breakpoint exception generated by the instruction 
int3. 

It constructs an EXCEPTI0N_REC0RD and then dispatches the exception. The 
EXCEPT 1 0N_REC0RD contains: 

Except ionCode = STATUS_BREAKP0INT; 

ExceptionFlags = 0; 

ExceptionRecord = 0; 

ExceptionAddress = Eip; 

NumberParameters = 3; 

ExceptionParameters[0] = 0; 

ExceptionParameters[ 1 ] = Ecx; 

ExceptionParameters[2] = Edx; 

The Ecx and Edx registers can be used to convey contextual information to an 
exception-handling routine. 
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KiTrap04 



KiTrap03 is the handler for the integer overflow exception generated by the instruc- 
tion into. It dispatches the exception STATUS_INTEGER_OVERFLOW. 



KiGetTickCount 



KiGetTickCount is a third method of obtaining the number of milliseconds that have 
elapsed since the system was booted. It is faster than calling ZwGetTickCount but 
slightly slower than reading from the KUSER_SHARED_DATA page. 

If KiGetTickCount is invoked from aVirtual DOS Machine, it invokes 
NtSetLdtEntries instead. 



KiCallbackReturn 



Invoking KiCallbackReturn is effectively the same as calling ZwCallbackReturn. 



KiSctLowWaitHighThrc ad 



KiSetLowWaitHighThread establishes most of the environment needed to call a system 
service, but instead of actually calling a service, it just returns STATUS_NO_EVENT_PAIR. 



KiDebugService 



KiDebugService constructs an EXCEPTION_RECORD and then dispatches the exception. 
The EXCEPT I0N_REC0RD contains: 

Except ionCode = STATUS_BREAKPOINT; 

ExceptionFlags = 0; 

ExceptionRecord = 0; 

ExceptionAddress = Eip; 

NumberParameters = 3; 

ExceptionParameters[0] = Eax; 

ExceptionParameters[1 ] = Ecx; 

ExceptionParameters[2] = Edx; 

Eax is set to the debug service code drawn from the enumeration 

DEBUG_SERVICE_CODE. 

typedef enum _DEBUG_SERVICE_CODE { 

DebugPrint = 1 , 

DebugPrompt , 

DebugLoadlmageSymbols , 

DebugllnLoadlmageSymbols 
} DEBUG_SERVICE_CODE ; 

Ecx points to a STRING that contains either a string to print or the name of an image. 

Edx contains or points to additional information, such as the base of an image or a 
prompt reply STRING. 
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When the kernel debugger is informed of a STATUS_BREAKPOINT exception, it checks 
ExceptionParameters[0] . If this value is zero, the exception was caused by an int3 
instruction; otherwise, the value should be one of the enumerated values in 
DEBUG_SERVICE_CODE. 

If no remote debugger is present, DebugPrint, DebugLoadlmageSymbols, and 
DebugUnLoadlmageSymbols exceptions are ignored; DebugPrompt and int3 exceptions 
are left to be handled by the standard exception-handling mechanisms. 



KiSystemService 



KiSystemService is the system service dispatcher; it is responsible for dispatching all of 
the system services described in the previous chapters. KiSystemService expects to 
find the system service code in the Eax register, and a pointer to the arguments of the 
system service in the Edx register. It checks that the system service code specifies a 
vafid dispatch descriptor table and a valid entry within the table. If so, the descriptor 
table specifies both the number of bytes to be copied from the memory pointed to by 
Edx to the kernel stack and the address of the routine to be called (which will be one 
of the NtXxx routines). 
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Exceptions and 
Debugging 



Exceptions can occur in both user mode and kernel mode code and can be generated 
by either the processor (such as “general protection,” “divide by zero,” or debug excep- 
tions) or by calling ZwRaiseException. Almost all exceptions eventually result in the 
kernel mode routine KiDispatchException being called. This routine is at the heart of 
the exception-handling and debugging support provided by the system, and its 
pseudocode appears in Example D. 1 . 






enum CHANCE { 
FirstChance, 
LastChance 

}; 

enum EVENT { 

ExceptionEvent , 
DebugEvent 



PCR->KeExceptionDispatchCount++; 

CONTEXT Context 

= {CONTEXT_FULL | (PreviousMode == UserMode ? CONTEXT_DEBUG : 0)}; 
KeContextFromKf rames(Tf , Reserved, &Context); 
if (Er->ExceptionCode == STATUS_BREAKPO I NT ) Context . Eip- ; 
do { 

if (PreviousMode == KernelMode) { 
if (SearchFrames) { 

if (KiDebugRoutine && 

KiDebugRoutine(Tf , Reserved, Er, &Context, 

PreviousMode, FirstChance) != 0) break; 




}; 



VOID KiDispatchException (PEXCEPTION_RECORD Er, ULONG Reserved 



PKTRAP_FRAME Tf, MODE PreviousMode, 
BOOLEAN SearchFrames) 
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if (RtlDispatchException(Er, &Context) == 1) break; 

} 

if (KiDebugRoutine && 

KiDebugRoutine(Tf , Reserved, Er, &Context, 

PreviousMode, LastChance) != 0) break; 

} 

else { 

if (SearchFrames) { 

if (PsGetCurrentProcess( ) ->DebugPort == 0 
|j KdIsThisAKdTrap(Tf , &Context)) { 

if (KiDebugRoutine && 

KiDebugRoutine (Tf, Reserved, Er, &Context, 

PreviousMode, FirstChance) != 0) break; 

} 

if (DbgkForwardException(Tf , DebugEvent, 

FirstChance) != 0) return; 

if (valid_user_mode_stack_with_enough_space) { 

// copy EXCEPTION_RECORD and CONTEXT to user mode stack; 

// push addresses of EXCEPTION_RECORD and CONTEXT 
// on user mode stack; 

Tf->Eip = KeUserExceptionDispatcher; 

return; 

} 

} 

if (DbgkForwardException(Tf , DebugEvent, 

LastChance) != 0) return; 

if (DbgkForwardException(Tf , ExceptionEvent , 

LastChance) != 0) return; 

ZwTerminateThread(NtCurrentThread( ) , Er->ExceptionCode) ; 

} 

KeBugCheckEx(KMODE_EXCEPTION_NOT_HANDLED, Er ->ExceptionCode , 

Er->ExceptionAddress, Er->ExceptionInformation[0] , 
Er->ExceptionInformation[ 1 ] ) ; 

} while (false) ; 



} 



KeContextToKf rames(Tf , Reserved, &Context, 

Context .ContextFlags, PreviousMode) ; 



KiDebugRoutine is a pointer to a function, and normally takes one of two values, 
depending on whether the system was booted with kernel mode debugging enabled 
(for example, /DEBUG was specified in boot.ini). 

There are two main paths through KiDispatchException that are selected according 
to the previous execution mode. 
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If the previous mode was kernel, the following steps are taken: 

• If frame-based exception-handling is allowed (SearchFrames == TRUE), the 
kernel debugger is given a first chance to handle the exception. 

• If the kernel debugger does not handle the exception, then 
RtlDispatchException is invoked to search for and invoke a frame-based 
exception handler. 

• If RtlDispatchException does not find a handler prepared to handle the excep- 
tion or if SearchFrames is FALSE, the kernel debugger is given a last chance to 
handle the exception. 

• Finally, if the exception has still not been handled, KeBugCheckEx is invoked to 
shut down the system with the bugcheck code KM0DE_EXCEPTI0N_N0T_HANDLED. 

If the previous mode was user, the following steps are taken: 

• If frame-based exception-handling is allowed (SearchFrames == TRUE) and if the 
process is not being debugged by a user mode debugger (Debug Port == 0), the 
kernel debugger is given a first chance to handle the exception; otherwise, a 
description of the exception is forwarded to the user mode debugger via the LPC 
mechanism. 

• If the exception is not handled by a debugger and the user mode stack appears to 
be still valid, the user mode context is adjusted so that upon return to user mode, 
the function KiUserExceptionDispatcher will be invoked. 

• After returning to user mode, KiUserExceptionDispatcher invokes 
RtlDispatchException to search for a frame-based exception handler. 

• If RtlDispatchException does not find a handler prepared to handle the excep- 
tion, the exception is re-signaled, specifying SearchFrames as FALSE. 

• KiDispatchException is entered again and, because SearchFrames is FALSE, the 
next step is to give a user mode debugger a last chance to handle the exception. 

• If the debugger (if any) still does not handle the exception, a description of the 
exception is forwarded to the exception port (if any) of the process. 

• The recipient (if any) of the message to the exception port can still handle the 
exception, but if it does not, ZwTerminateThread is called to terminate the cur- 
rent thread. 

• If ZwTerminateThread fails for any reason, KeBugCheckEx is invoked to shut down 
the system with the bugcheck code KM0DE_EXCEPTI0N_N0T_HANDLED. 



Example D.2: Pseudocode for KiUserExceptionDispatcher 



VOID KiUserExceptionDispatcher(PEXCEPTION_RECORD ExceptionRecord, PCONTEXT Context) 

{ 

NTSTATUS rv = RtlDispatchException(ExceptionRecord, Context) == 1 
? ZwContinue (Context , FALSE) 

: ZwRaiseException (ExceptionRecord, Context, FALSE); 

EXCEPTI0N_REC0RD NestedExceptionRecord 
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= {rv, EXCEPTIONJIONCONTINUABLE, ExceptionRecord} ; 
RtlRaiseException(&NestedExceptionRecord) ; 

} 

Example D.2 shows how KiUserExceptionDispatcher uses the two system services, 
ZwContinue and ZwRaiseException. As mentioned previously, 
KiUserExceptionDispatcher first calls RtlDispatchException to find and invoke a 
frame-based exception handler. An exception handler can modify the Context structure 
(which it accesses by calling GetExceptionlnf ormation). Therefore, if 
RtlDispatchException finds a handler, upon return from the handler, ZwContinue is 
invoked to modify the execution context of the current thread to make it the one that 
is specified by the handler. If a handler is not found, ZwRaiseException is called to 
re-signal the exception. If either ZwContinue or ZwRaiseException return, a nested, 
noncontinuable exception is raised. 

All threads created by Win32 functions have a top-level frame-based exception 
handler; the behavior of this handler can be influenced by calling the Win32 function 
SetUnhandledExceptionFilter.This functionality allows a last-chance??? handler to 
be defined, which handles the unhandled exceptions of all threads in a process. There 
is no mechanism defined to provide a first-chance handler (which would have the 
chance to handle the exceptions of all threads before searching the thread’s stack for 
frame-based handlers), but by knowing how exception dispatching works, it is possible 
to provide this functionality by patching the binary code of 

KiUserExceptionDispatcher. (There are resource kit— like utilities that actually do 
this) . 



The Kernel Debugger 



The principal link between the kernel debugger and the kernel itself are the call-outs 
to the kernel debugger (KiDebugRoutine) embedded in the kernel routine 
KiDispatchException.The only other essential link is the check performed by 
KeUpdateSystemTime for input from a remote debugger (for example, a Ctrl-C break- 
in); if input is detected, KeUpdateSystemTime generates an exception by calling 
DbgBreakPointWithStatus, which eventually results in the KiDispatchException 
kernel debugger call-outs being invoked. 

Other kernel components that wish to inform the kernel debugger of some event call 
DebugService, which ultimately conveys the information to the kernel debugger by 
raising an exception. 



Example D.3: Pseudocode for DebugService 



typedef enum _DEBUG_SERVICE_CODE { 
DebugPrint = 1 , 

DebugPrompt , 
DebugLoadlmageSymbols, 
DebugUnLoadlmageSymbols 
} DEBUG_SERVICE_CODE ; 



NTSTATUS DebugService (DEBUG_SERVICE_CODE Opcode, PSTRING String, PVOID Data) 
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{ 



NTSTATUS rv; 



asm { 

mov 


eax, 


Opcode 


mov 


ecx, 


String 


mov 


edx, 


Data 


int 


0x2D 




int 


0x03 




mov 


rv, 


eax 


} 

return rv; 







} 

As was mentioned in Appendix B, “Intel Platform-Specific Entry Points to Kernel 
Mode,” the instruction “int 0x2D” invokes KiDebugService, which saves the values of 
selected registers in an EXCEPTION_RECORD structure and then raises a STATUS_BREAK- 
POINT exception. When KiDispatchException is invoked to handle the exception and 
KiDebugRoutine is called, the kernel debugger recognizes the exception as coming 
from KiDebugService (because the EXCEPTION_RECORD member 
ExceptionParameters[0] is non-zero) and responds accordingly. 

Two kernel routines that inform the kernel debugger of events using this mechanism 
are MmLoadSystemlmage and MmUnloadSystemlmage. (This is how the kernel debugger 
learns of the loading and unloading of device drivers). 

As was mentioned earlier, KiDebugService is a pointer to a function, and it normally 
points at one of two routines. If kernel debugging is enabled (by specifying /DEBUG 
in boot.ini, for example), KiDebugService points to KdpTrap; otherwise, it points to 
KdpStub. 

KdpStub checks whether the exception is a STATUS_BREAKPOINT with a recognized 
DEBUG_SERVICE_CODE that can be ignored (all except DebugPrompt can be ignored) 
and, if so, returns one to KiDispatchException, indicating that the exception has been 
handled. KdpStub also does what is necessary to support ZwSystemDebugControl. 

KdpTrap implements the full kernel debugger raising functionality and can, if necessary, 
freeze the operation of the system and interact with a remote debugger via the serial 
line. 



User Mode Debuggers 



At five points in the kernel (as described below), a check is made as to whether the 
current process has a debug port; if it does, then an LPC message is constructed 
describing the event that has just occurred. All threads (except the current) are frozen 
and the message is sent to the debug port. When a reply is received, the frozen threads 
are thawed. 

The five points in the kernel at which checks are made are: 

• Thread creation routine 

• Thread termination routine 

• Executable image-mapping routine 

• Executable image-unmapping routine 

• Exception dispatching routine (KiDispatchException, described earlier) 
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The message sent to the debug port is a DEBUG_MESSAGE structure, which bears a 
resemblance to the Win32 DEBUG EVENT structure. 



DEBUG JVLESSAGE 



typedef struct _DEBUG_MESSAGE { 

PORT_MESSAGE PortMessage; 

ULONG EventCode; 

ULONG Status; 
union { 

struct { 

EXCEPTION_RECORD ExceptionRecord ; 

ULONG FirstChance; 

} Exception; 
struct { 

ULONG Reserved; 

PVOID StartAddress; 

} CreateThread; 
struct { 

ULONG Reserved; 

HANDLE FileHandle; 

PVOID Base; 

ULONG PointerToSymbolTable; 

ULONG NumberOf Symbols; 

ULONG Reserved2; 

PVOID EntryPoint; 

} CreateProcess; 
struct { 

ULONG ExitCode; 

} ExitThread; 
struct { 

ULONG ExitCode; 

} ExitProcess; 
struct { 

HANDLE FileHandle; 

PVOID Base; 

ULONG PointerToSymbolTable; 

ULONG NumberOf Symbols; 

} LoadDll; 
struct { 

PVOID Base; 

} UnloadDll; 

} u; 

} DEBUG_MESSAGE, *PDEBUG_MESSAGE; 

Some of the messages include handles that are valid in the context of the debuggee. 
Example 20.4 demonstrates how to implement debugger- type functionality by directly 
receiving and replying to these messages. 



Debug Message Routing 



The debug port ofWin32 processes being debugged is normally the general function 
port for the Win32 subsystem process (the port named “\Windows\ApiPort”) rather 
than a port created by the debugger itself. 
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Exceptions and Debugging: Value Added by the Routing Process 

There are routines in ntdll.dll intended for use by environment subsystems to perform 
the bulk of debug message processing. By default, these routines repackage the message 
slightly and forward it to the port named “\DbgSsApiPort,” but they allow the 
subsystem to customize their behavior by registering callback functions. The Win32 
subsystem process (csrss.exe) does not add any significant functionality to the forward- 
ing process. 

The process that listens to the port named “\DbgSsApiPort” is the Session Manager 
(smss.exe), which acts as a switch and monitor between applications and debuggers. 
Debuggers register with the Session Manager by connecting to the port named 
“\DbgUiApiPort.” 

The Session Manager receives messages from the port named “\DbgSsApiPort,” 
repackages their contents again (duplicating any handles into the debugger) and for- 
wards the message to the debugger. 

When the debugger replies to the message specifying the “continue status,” the Session 
Manager forwards the reply to Win32 subsystem process, which forwards it in turn to 
the debuggee. 



Value Added by the Routing Process 



When a variant of Example D.4 that uses the Win32 debugging API (rather than the 
native API) is run, a consequence of the routing of the debug messages through vari- 
ous processes is that the CPU load is roughly evenly divided between the debuggee, 
the Session Manager, the Win32 subsystem, and the debugger. So it is worthwhile con- 
sidering the value that each process adds. 

The Win32 subsystem process does not add any significant value when debugging a 
newly created process, but it does provide important functionality in support of the 
Win32 DebugActiveProcess function: It fabricates process and thread creation debug 
messages for the existing threads and image-mapping events for the loaded DLLs of 
the debuggee. 

The Session Manager ensures that the debuggee is terminated if the debugger termi- 
nates. A debuggee waiting for a debugger to reply to a debug message cannot be ter- 
minated, so if the debugger were to terminate and the debuggee were allowed to con- 
tinue running, the next debug event to occur (as a result of thread creation, DLL load- 
ing, or exception) would cause the debuggee to enter a state from which it could not 
be continued or terminated. 

The Session Manager also signals the availability of messages to the debugger by sig- 
naling a semaphore; this allows a debugger to timeout a wait for a debug event. This 
was necessary in Windows NT 4.0, because, as conventional ports are not waitable 
objects, it is not possible to use ZwWaitForSingleOb ject to wait on them. The wait- 
able ports introduced with Windows 2000 or the new ZwReplyWaitReceivePortEx 
system service could also be used to tackle this problem, but in practice the Windows 
NT 4.0 architecture has been retained. 
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OutputDebugString 



OutputDebugString communicates its string to the debugger by raising an exception 
with a particular code (0x40010006); if not recognized and handled by a debugger, a 
frame-based exception handler is invoked, which makes the string available to debug 
string monitors (such as dbmon.exe) by copying it to a file mapping and signaling an 
event. 



Tracing Calls to Routines Exported by DLLs 



Example D.4 demonstrates the direct manipulation of the debug port of a process. The 
example traces calls to the exported routines of all the DLLs that are loaded in a 
process and runs in about 60 percent of the time required by a variant using the 
Win32 debugging API. The level of tracing is more detailed than that produced by 
utilities that patch the image export directories of the loaded DLLs, but the tracing 
consumes substantially more CPU time. An application being traced runs at about one 
twentieth of its normal speed. 



Example D.4: A Trace Utility 



#include "ntdll.h" 

#include <imagehlp.h> 

#include <stdlib.h> 

#include <stdio.h> 

#include <vector> 

#include <map> 

#define elements(s) (sizeof (s) / sizeof *(s)) 

namespace NT { 
extern "C" { 

typedef struct _DEBUG_MESSAGE { 

P0RT_MESSAGE PortMessage; 

ULONG EventCode; 

ULONG Status; 
union { 

struct { 

EXCEPTI0N_REC0RD ExceptionRecord ; 
ULONG FirstChance; 

} Exception; 
struct { 

ULONG Reserved; 

PVOID StartAddress; 

} CreateThread; 
struct { 

ULONG Reserved; 

HANDLE FileHandle; 

PVOID Base; 

ULONG PointerToSymbolTable; 

ULONG NumberOf Symbols; 

ULONG Reserved2; 

PVOID EntryPoint; 

} CreateProcess; 
struct { 

ULONG ExitCode; 
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} ExitThread; 
struct { 

ULONG ExitCode; 

} ExitProcess; 
struct { 

HANDLE FileHandle; 

PVOID Base; 

ULONG PointerToSymbolTable; 
ULONG NumberOf Symbols; 

} LoadDll; 
struct { 

PVOID Base; 

} UnloadDll; 

} u; 

} DEBUG_MESSAGE, *PDEBUG_MESSAGE ; 

} 

} 



typedef struct 
ULONG B0 : 
ULONG B1 : 
ULONG B2 : 
ULONG B3 : 
ULONG : 

ULONG BD : 
ULONG BS : 
ULONG BT : 
ULONG : 

} DEBUG_STATUS, 



_DEBUG_STATUS { 

1 ; 

1 ; 

1 ; 

1 ; 

9; 

1 ; 

1 ; 

1 ; 



16; 

*PDEBUG_STATUS; 



typedef struct _DEBUG_C0NTR0L { 



ULONG L0 


1 


ULONG G0 


1 


ULONG LI 


1 


ULONG G1 


1 


ULONG L2 


1 


ULONG G2 


1 


ULONG L3 


1 


ULONG G3 


1 


ULONG LE 


1 


ULONG GE 


1 


ULONG 


3 


ULONG GD 


1 


ULONG 


2 


ULONG RWE0 : 


ULONG LEN0 : 


ULONG RWE1 : 


ULONG LEN1 : 


ULONG RWE2 : 


ULONG LEN2 : 


ULONG RWE3 : 


ULONG LEN3 : 



} DEBUG_CONTROL, 



2 ; 

2 ; 

2 ; 

2 ; 

2 ; 

2 ; 

2 ; 

2 ; 

*PDEBUG_CONTROL ; 



struct Error { 

ULONG line; 

ULONG code; 

Error(ULONG line, ULONG code) : line(line), code(code) {} 

}; 



struct enter { 
PCSTR name; 
BYTE opcode; 
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ULONG argc; 

enter() : name(0), opcode(0), argc(0) {} 

enter(PCSTR n, BYTE o = 0, ULONG a = 3) : name(n), opcode(o), argc(a) {} 



struct leave { 

PVOID eip; 

ULONG esp; 

leave () : eip(0), esp(0) {} 

leave(PVOID ip, ULONG sp) : eip(ip), esp(sp) {} 

}; 



#pragma warning(disable:4786) 

typedef std: :map<UL0NG, std: :vector<leave>, std : : less<ULONG> > leaves_t; 
typedef std: :map<PV0ID, enter, std: :less<PVOID> > enters_t; 
typedef std: :map<ULONG, PVOID, std: :less<ULONG> > steps_t; 



enters_t enters; 
leaves_t leaves; 
steps_t steps; 

std: :map<ULONG, HANDLE, std : : less<ULONG> > threads; 

HANDLE hProcess; 

ULONG StartTime; 

BOOL Discard; 

const int EXECUTE = PAGE_EXECUTE j PAGE_EXECUTE_READ 

| PAGE_EXECUTE_READWRITE | PAGE_EXECUTE_WRITECOPY; 



BYTE InsertBreakPoint (PVOID addr) 

{ 

MEMORY_BAS I CONFORMATION mbi; 

ULONG rv; 

BYTE op, bp = 0xcc; 

rv = VirtualQueryEx(hProcess, addr, &mbi, sizeof mbi); 
if (rv != sizeof mbi) return bp; 

if ( (mbi. Protect & EXECUTE) == 0) return bp; 

rv = ReadProcessMemory (hProcess, addr, &op, sizeof op, 0); 
if (rv == FALSE) return bp; 

rv = WriteProcessMemory (hProcess, addr, &bp, sizeof bp, 0); 
if (rv == FALSE) return bp; 

return op; 

} 

VOID ReinsertBreakPoint (PVOID addr) 

{ 

BYTE bp = 0xcc; 



BOOL rv = WriteProcessMemory (hProcess, addr, &bp, sizeof bp, 0); 
if (rv != TRUE) throw Error( LINE , GetLastError ( ) ) ; 



VOID StepBreakPoint ( PCONTEXT context, ULONG tid, PVOID addr, BYTE opcode) 

{ 

BOOL rv = WriteProcessMemory (hProcess, addr, &opcode, sizeof opcode, 0); 
if (rv != TRUE) throw Error( LINE , GetLastError( ) ) ; 



steps[tid] = addr; 
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context ->EFlags [= 0x100; 
context->Eip -= 1 ; 



ULONG ReturnBreak(PCONTEXT context, PVOID addr, ULONG tid) 

{ 

std: : vector<leave>& stack = leaves[tid]; 

while (! stack. empty () && stack. back( ) .esp < context->Esp) { 
stack. pop_back() ; 
printf ( "#" ) ; 

} 

if (addr == 0) return 0; 

stack . push_back(leave(addr, context->Esp) ) ; 

PDEBUG_C0NTR0L dr7 = PDEBUG_C0NTR0L(&context->Dr7) ; 

PDEBUG_STATUS dr6 = PDEBUG_STATUS(&context ->Dr6) ; 

context->Dr0 = ULONG(addr); 

dr7->L0 = 1, dr7->RWE0 = 0, dr7->LEN0 = 0, dr6->B0 = 0; 
return stack. size() - 1; 

} 

VOID AddFPO( PVOID base, PSTR name) 

{ 

PIMAGE_DEBUG_INFORMATION idi 

= MapDebugInformation(0, name, getenv( "_NT_SYMBOL_PATH" ) , 0); 
if (idi == 0) return; 



for (ULONG i = 0; i < idi->NumberOfFpoTableEntries; i++) { 

PVOID func = PVOID (PBYTE (base) + idi->FpoTableEntries[i] .ulOffStart) ; 

enters_t :: iterator entry = enters. find(func) ; 

if (entry != enters. end( ) ) 

entry->second . argc = idi->FpoTableEntries[i] .cdwParams; 

} 

UnmapDebuglnformation(idi) ; 

} 

VOID InsertBreakPoints(PVOID base) 

{ 

I MAG E_DOS_H E AD E R dos; 

I MAG E_NT_HEADERS nt; 

BOOL rv; 

rv = ReadProcessMemory (hProcess, base, 

&dos, sizeof dos, 0) ; 

if (rv != TRUE) throw Error( LINE , GetLastError( ) ) ; 

rv = ReadProcessMemory (hProcess, PBYTE(base) + dos.e_lfanew, 

&nt, sizeof nt, 0); 

if (rv != TRUE) throw Error( LINE , GetLastError( ) ) ; 

P I MAG E_DAT A_D IRECTORY expdir 

= nt .OptionalHeader.DataDirectory + IMAGE_DIRECTORY_ENTRY_EXPORT; 
ULONG size = expdir->Size; 

ULONG addr = expdir->VirtualAddress; 
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PIMAGE_EXPORT_DI RECTORY exports = PIMAGE_EXPORT_DIRECTORY(malloc(size) ) 

rv = ReadProcessMemory (hProcess, PBYTE(base) + addr, exports, size, 0); 
if (rv != TRUE) throw Error( LINE , GetLastError( ) ) ; 

PULONG functions = PUL0NG( PBYTE (exports) - addr 

+ ULONG(exports->AddressOfFunctions) ) ; 
PUSHORT ordinals = PUSH0RT( PBYTE (exports) - addr 

+ ULONG(exports->AddressOfNameOrdinals) ) ; 
PULONG fnames = PULONG (PBYTE (exports) - addr 

+ ULONG(exports->AddressOf Names) ) ; 

for (ULONG i = 0; i < exports ->NumberOf Names; i++) { 

ULONG ord = ordinals[i]; 

if (functions[ord] < addr j \ functions[ord] >= addr + size) { 

PBYTE func = PBYTE(base) + functions[ord] ; 

PSTR name = PSTR( PBYTE (exports) - addr + fnames[i]); 

BYTE op = InsertBreakPoint (func) ; 

if (enters .find(func) == enters . end( ) ) 
enters[func] = enter(name, op); 

} 

} 

AddFPO(base, PSTR (PBYTE (exports) - addr + exports->Name) ) ; 

} 

VOID RemoveDeadBreakPoints( ) 

{ 

enters_t dead(enters) ; 

BYTE op; 

for (enters_t :: iterator entry = dead. begin () ; 
entry != dead.end(); entry++) 
if (ReadProcessMemory (hProcess, entry->first , 

&op, sizeof op, 0) == FALSE) 
enters.erase(entry->first) ; 

} 

VOID ReportEntry (PCONTEXT context, NT: : PDEBUG_MESSAGE dm) 

{ 

ULONG stack[17] ; 

CHAR buf [512] ; 

PVOID addr = dm->u. Exception. ExceptionRecord.ExceptionAddress; 
enter& entry = enters[addr] ; 

PCSTR s = entry. name; 

if (*s == '?' && UnDecorateSymbolName(s, buf, sizeof buf - 1, 0) >0) 
s = buf; 

ULONG argc = min(ULONG(elements(stack) ) - 1, entry. argc); 

BOOL rv = ReadProcessMemory (hProcess, PVOID(context->Esp) , 

stack, sizeof stack[0] * (1 + argc), 0); 



ULONG now = GetTickCount ( ) - StartTime; 
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ULONG n = rv ? ReturnBreak(context , PVOID(stack[0] ) , 

ULONG ( dm ->PortMessage. Client Id .UniqueThread) ) 

: 0 ; 

printf ("\n%4d.%02d %4x %*s%s(", 

now / 1000, (now % 1000) / 10, 

ULONG(dm->PortMessage. Clientld. UniqueThread) , n, s); 

if (rv == TRUE) { 
switch (argc) { 
case 0: break; 

case 1: printf("%x", stack [ 1 ] ) ; break; 

case 2: printf ("%x, %x", stack[1], stack[2]); break; 

case 3: printf ("%x, %x, %x", stack[1], stack[2], stack[3]); break; 

default: 

printf ("%x, %x, %x, %x", stack[1], stack[2], stack[3], stack[4]); 
for (ULONG i = 5; i <= argc; i++) printf (", %x", stack [ i] ) ; 

} 

} 

printf (")"); 

} 

VOID ReportExit (PCONTEXT context) 

{ 

printf(" ->%x", context->Eax) ; 

} 

ULONG HandleBreakPoint (NT : : PDEBUG_MESSAGE dm) 

{ 

PVOID addr = dm->u. Exception. ExceptionRecord.ExceptionAddress; 

enters_t :: iterator entry = enters. find(addr) ; 

if (entry != enters. end() && entry->second. opcode != 0xcc) { 

HANDLE hThread 

= threads[ULONG(dm->PortMessage.ClientId.UniqueThread) ] ; 

CONTEXT context; 

context. ContextFlags = CONTEXT_DEBUG_REGISTERS j CONTEXT_CONTROL ; 
GetThreadContext (hThread, &context) ; 

ReportEntry (&context , dm); 

StepBreakPoint (&context , ULONG ( dm ->PortMessage. Client Id. UniqueThread) , 
addr, entry->second. opcode) ; 

SetThreadContext (hThread, &context) ; 

} 

else { 

if (entry != enters. end() && entry->second . name != 0) 

printf (" \nDebug exception at %s\n", entry->second . name) ; 

else 

printf (" \nDebug exception at %p\n", addr); 

} 

return DBG_CONTINUE; 

} 

ULONG HandleSingleStep ( NT : : PDEBUG_MESSAGE dm) 
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CONTEXT context; 
steps_t: : iterator step 

= steps.find(ULONG(dm->PortMessage.ClientId.UniqueThread) ) ; 

if (step ! = steps. end()) { 

if (IDiscard) ReinsertBreakPoint (step->second) ; 

steps. erase(step) ; 

return DBG_CONTINUE; 



PVOID eaddr = dm->u . Exception . ExceptionRecord . ExceptionAddress; 
std: : vector<leave>& stack 

= leaves[ULONG(dm->PortMessage.ClientId.UniqueThread) ] ; 
if (! stack. empty () && stack. back ( ) .eip == eaddr) stack. pop_back( ) ; 

PVOID iaddr = stack. empty( ) ? 0 : stack. back( ) .eip; 

HANDLE hThread = threads[ULONG(dm->PortMessage.ClientId.UniqueThread) ] ; 
context .ContextFlags 

= CONTEXT_DEBUG_REGISTERS j C0NTEXT_C0NTR0L | CONTEXT_INTEGER ; 

GetThreadContext (hThread, &context) ; 

PDEBUG_C0NTR0L dr7 = PDEBUG_CONTROL(&context .Dr7) ; 

PDEBUG_STATUS dr6 = PDEBUG_STATUS(&context . Dr6) ; 

context. Dr0 = ULONG(iaddr) ; 

dr7->L0 = 1, dr7->RWE0 = 0, dr7->LEN0 = 0, dr6->B0 = 0; 
if (iaddr == eaddr) context .EFlags |= 0x100, dr7->L0 = 0; 
SetThreadContext (hThread, &context) ; 

ReportExit (&context) ; 
return DBG_CONTINUE; 



ULONG HandleExceptionEvent (NT : : PDEBUG_MESSAGE dm) 

{ 

switch (dm->u . Exception . ExceptionRecord . ExceptionCode) { 
case EXCEPTION_BREAKPOINT : 
return HandleBreakPoint (dm) ; 

case EXCEPTION_SINGLE_STEP: 
return HandleSingleStep(dm) ; 

default: 

printf ( " \nException %x at %p\n" , 

dm ->u . Exception . ExceptionRecord . ExceptionCode , 
dm ->u . Exception . ExceptionRecord . ExceptionAddress ) ; 



return DBG_EXCEPTION_NOT_HANDLED ; 



} 
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ULONG HandleCreateProcessThreadEvent (NT: : PDEBUG_MESSAGE dm) 

{ 

printf ( " \nProcess %x, Thread create %x\n" , 

dm ->PortMessage . Client Id . UniqueProcess , 
dm->PortMessage . Client Id . UniqueThread) ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa}; 

HANDLE hThread; 

NT: :ZwOpenTh read (&hTh read, THREAD_ALL_ACCESS , 

&oa, &dm->PortMessage.ClientId) ; 

t hreads[ ULONG ( dm ->PortMessage .Client Id .UniqueThread) ] 

= hThread; 

leaves [ ULONG ( dm ->PortMessage. Client Id .UniqueThread) ] 

= std: :vector<leave>() ; 

return DBG_CONTINUE; 

} 

ULONG HandleExitThreadEvent (NT : : PDEBUG_MESSAGE dm) 

{ 

printf (" \nThread %x exit code %x\n", 

dm ->PortMessage. Client Id .UniqueThread, 
dm->u.ExitThread.ExitCode) ; 

leaves. erase ( ULONG ( dm ->PortMessage. Client Id .UniqueThread) ) ; 
return DBG_CONTINUE; 

} 

ULONG HandleExitProcessEvent (NT : : PDEBUG_MESSAGE dm) 

{ 

printf (" \nProcess %x exit code %x\n", 

dm ->PortMessage . Client Id . UniqueProcess , 
dm ->u. Exit Process. ExitCode) ; 

leaves. erase ( ULONG ( dm ->PortMessage. Client Id .UniqueThread) ) ; 
return DBG_CONTINUE; 

} 

ULONG HandleLoadDllEvent ( NT : : PDEBUG_MESSAGE dm) 

{ 

InsertBreakPoints(dm->u . LoadDll.Base) ; 
return DBG_CONTINUE; 

} 

ULONG HandleUnloadDllEvent (NT : : PDEBUG_MESSAGE) 

{ 

RemoveDeadBreakPoints( ) ; 
return DBG_CONTINUE; 

} 

BOOL WINAPI HandlerRoutine (ULONG event) 

{ 

if (event != CTRL_C_EVENT | | Discard == TRUE) 
TerminateProcess(hProcess, 0); 

if (event == CTRL_C_EVENT) 
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Discard = TRUE; 
return TRUE; 

} 

HANDLE StartDebuggee( HANDLE hPort) 

{ 

PR0CESS_INF0RMATI0N pi; 

STARTUPINFO si = {sizeof si}; 

PSTR cmd = strchr(GetCommandLine( ) , 1 ') + 1; 

CreateProcess(0, cmd, 0, 0, 0, CREATE_SUSPENDED, 0, 0, &si, &pi); 

NT : :ZwSetInformationProcess(pi.hProcess, NT : : ProcessDebugPort , 
&hPort, sizeof hPort); 



ResumeThread(pi. hThread) ; 

CloseHandle(pi.hThread) ; 

return pi.hProcess; 

} 

int main(int argc, wchar_t *argv[]) 

{ 

if (argc == 1) return 0; 

SetConsoleCtrlHandler(HandlerRoutine, TRUE) ; 

NT: :OBJECT_ATTRIBUTES oa = {sizeof oa}; 

HANDLE hPort; 

NT: :ZwCreatePort (&hPort, &oa, 0, 0x78, 0); 

hProcess = StartDebuggee(hPort) ; 

StartTime = GetTickCount ( ) ; 

NT : : DEBUG_MESSAGE dm; 

do { 

NT: :ZwReplyWaitReceivePort ( hPort, 0, 0, &dm. PortMessage) ; 
try { 

switch (dm. EventCode + 1) { 
case EXCEPTION_DEBUG_EVENT : 

dm. Status = HandleExceptionEvent (&dm) ; 
break; 

case CREATE_THREAD_DEBUG_EVENT : 
case CREATE_PROCESS_DEBUG_EVENT : 

dm. Status = HandleCreateProcessThreadEvent (&dm) ; 
break; 

case EXIT_THREAD_DEBUG_EVENT : 

dm. Status = HandleExitThreadEvent (&dm) ; 
break; 

case EXIT_PROCESS_DEBUG_EVENT : 

dm. Status = HandleExitProcessEvent (&dm) ; 
break; 
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case LOAD_DLL_DEBUG_EVENT: 
dm. Status = HandleLoadDllEvent (&dm) ; 
break; 

case UNLOAD_DLL_DEBUG_EVENT : 

dm. Status = HandleUnloadDllEvent (&dm) ; 
break; 

default: 

dm. Status = DBG_CONTINUE; 

printf ( " \nUnusual event %lx\n", dm. EventCode) ; 
break; 

} 

} 

catch (Error e) { 

printf ( "Error %ld on line %ld\n", e.code, e.line); 
dm. EventCode = EXIT_PROCESS_DEBUG_EVENT - 1; 

} 

NT : :ZwReplyPort (hPort , &dm.PortMessage) ; 

} while (dm. EventCode + 1 != EXIT_PROCESS_DEBUG_EVENT) ; 
return 0; 

} 

As a utility, Example D.4 is useful for understanding the relationship between Win32 
functions and the native system services. By attempting to show the call nesting, this 
example makes it possible to see which system services are invoked during a call to a 
Win32 function. 

Contrary to the advice of — “Don’t document bugs — fix them!” one known problem 
with Example D.4 is that it does not suspend all the other threads in the process while 
single stepping a thread over a breakpoint. This would potentially allow other threads 
to call an exported function when the breakpoint instruction at its entry point is tem- 
porarily removed. 
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E 

NTFS On-Disk 

Structure 



One of the interesting file system control operations defined in winioctl.h is 
FSCTL_GET_NTFS_FILE_RECORD, which retrieves a file record from the Master File Table 
(MFT) on an NTFS volume. When calling ZwFsControlFile (or the Win32 function 
DeviceloControl) with this control code, the InputBuffer parameter points to a 
NTFS_FILE_RECORD_INPUT_BUFFER structure, and the OutputBuffer parameter points to a 
buffer large enough to hold a NTFS_FILE_RECORD_OUTPUT_BUFFER structure and a file 
record. 

typedef struct { 

ULONGLONG FileRef erenceNumber ; 

} NTFS_FILE_RECORD_INPUT_BUFFER, *PNTFS_FILE_RECORD_INPUT_BUFFER; 

typedef struct { 

ULONGLONG FileRef erenceNumber ; 

ULONG FileRecordLength; 

UCHAR FileRecordBuffer[ 1 ] ; 

} NTFS_FILE_RECORD_OUTPUT_BUFFER, *PNTFS_FILE_RECORD_OUTPUT_BUFFER; 

Strictly speaking, a FileRef erenceNumber consists of a 48-bit index into the Master File 
Table and a 16-bit sequence number that records how many times the entry in the 
table has been reused, but the sequence number is ignored when using 
FSCTL_GET_NTFS_FILE_RECORD. Therefore, to retrieve the file record at index 30, the 
value 30 should be assigned to FileRef erenceNumber. If the table entry at index 30 is 
empty, FSCTL_GET_NTFS_FILE_RECORD retrieves a nearby entry that is not empty. To veri- 
fy that the intended table entry has been retrieved, it is necessary to compare the low 
order 48 bits of FileReferenceNumber in the output buffer with that in the input 
buffer. 

The remainder of this chapter describes the data structures that represent the on- 
disk structure of NTFS. It includes a sample utility that interprets the data structures 
to recover the data of a deleted file. The descriptions of the on-disk data structures also 
serve to explain the contents of the FileRecordBuf f er returned by 
FSCTL GET NTFS FILE RECORD. 
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NTFS_RECORD_HEADER 



typedef struct { 

ULONG Type; 

USHORT UsaOffset ; 

USHORT UsaCount; 

USN Usn; 

} NTFS_RECORD_HEADER , *PNTFS_RECORD_HEADER ; 

Members 

Type 

The type of NTFS record. When the value of Type is considered as a sequence of four 
one-byte characters, it normally spells an acronym for the type. Defined values include: 

'FILE' 

1 INDX 1 
1 BAAD 1 
'HOLE' 

' CHKD 1 



UsaOffset 

The offset, in bytes, from the start of the structure to the Update Sequence Array. 

UsaCount 

The number of values in the Update Sequence Array. 

Usn 

The Update Sequence Number of the NTFS record. 

Remarks 

None. 



FILE_RECORD_HEADER 



typedef struct { 

NTFS_RECORD_HEADER Ntfs; 

USHORT SequenceNumber; 

USHORT LinkCount; 

USHORT AttributesOff set ; 

USHORT Flags; // 0x0001 = InUse, 0x0002 = Directory 

ULONG BytesInUse; 

ULONG BytesAllocated; 

ULONGLONG BaseFileRecord ; 

USHORT NextAttributeNumber; 

} FILE_RECORD_HEADER, *PFILE_RECORD_HEADER ; 

Members 



An NTFS_RECORD HEADER structure with a Type of ‘FILE’. 
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SequenceNumber 

The number of times that the MFT entry has been reused. 

LinkCount 

The number of directory links to the MFT entry. 

Attribute Offset 

The offset, in bytes, from the start of the structure to the first attribute of the MFT 
entry. 

Flags 

A bit array of flags specifying properties of the MFT entry. The values defined include: 

Inllse 0x0001 // The MFT entry is in use 

Directory 0x0002 // The MFT entry represents a directory 



BytesInUse 

The number of bytes used by the MFT entry 

BytesAllocated 

The number of bytes allocated for the MFT entry 

BaseFileRecord 

If the MFT entry contains attributes that overflowed a base MFT entry, this member 
contains the file reference number of the base entry; otherwise, it contains zero. 

NextAttributeNumber 

The number that will be assigned to the next attribute added to the MFT entry. 

Remarks 

An entry in the MFT consists of a FILE_RECORD_HEADER followed by a sequence of 
attributes. 



ATTRIBUTE 



typedef struct { 

ATTRIBUTEJTYPE AttributeType; 

ULONG Length; 

BOOLEAN Nonresident; 

UCHAR NameLength; 

USHORT NameOffset; 

USHORT Flags; // 0x0001 = Compressed 

USHORT AttributeNumber; 

} ATTRIBUTE, *PATTRIBUTE; 
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Members 

AttributeType 

The type of the attribute. The following types are defined: 
typedef enum { 

AttributeStandardlnformation = 0x10, 
AttributeAttributeList = 0x20, 

AttributeFileName = 0x30, 

AttributeObjectld = 0x40, 
AttributeSecurityDescriptor = 0x50, 
AttributeVolumeName = 0x60, 
AttributeVolumelnformation = 0x70, 

AttributeData = 0x80, 

AttributelndexRoot = 0x90, 
AttributelndexAllocation = 0xA0, 

AttributeBitmap = 0xB0, 

AttributeReparsePoint = 0xC0, 
AttributeEAInformation = 0xD0, 

AttributeEA = 0xE0, 

AttributePropertySet = 0xF0, 
AttributeLoggedlltilityStream = 0x100 
} ATTRIBUTE_TYPE , *PATTRIBUTE_TYPE; 



Length 

The size, in bytes, of the resident part of the attribute. 

Nonresident 

Specifies, when true, that the attribute value is nonresident. 

NameLength 

The size, in characters, of the name (if any) of the attribute. 

Name Offset 

The offset, in bytes, from the start of the structure to the attribute name. The attribute 
name is stored as a Unicode string. 

Flags 

A bit array of flags specifying properties of the attribute. The values defined include: 
Compressed 0x0001 // The attribute is compressed 

AttributeNumber 

A numeric identifier for the instance of the attribute. 



Remarks 

None. 
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RESIDENT_ATTRIBUTE 



typedef struct { 

ATTRIBUTE Attribute; 

ULONG ValueLength; 

USHORT ValueOffset ; 

USHORT Flags; // 0x0001 = Indexed 

} RESIDENT_ATTRIBUTE , *PRESIDENT_ATTRIBUTE; 

Members 

Attribute 

An ATTRIBUTE structure containing members common to resident and nonresident 
attributes. 

ValueLength 

The size, in bytes, of the attribute value. 

ValueOffset 

The offset, in bytes, from the start of the structure to the attribute value. 

Flags 

A bit array of flags specifying properties of the attribute. The values defined include: 
Indexed 0x0001 // The attribute is indexed 

Remarks 

None. 



NONRESIDENT_ATTRIBUTE 



typedef struct { 

ATTRIBUTE Attribute; 

ULONGLONG LowVcn; 

ULONGLONG HighVcn; 

USHORT RunArrayOff set ; 

UCHAR CompressionUnit ; 

UCHAR Alignment0rReserved[5] ; 

ULONGLONG AllocatedSize; 

ULONGLONG DataSize; 

ULONGLONG InitializedSize ; 

ULONGLONG CompressedSize ; // Only when compressed 

} NONRESIDENT_ATTRIBUTE , *PNONRESIDENT_ATTRIBUTE; 

Members 

Attribute 

An ATTRIBUTE structure containing members common to resident and nonresident 
attributes. 
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LowVcn 

The lowest valid Virtual Cluster Number (VCN) of this portion of the attribute value. 
Unless the attribute value is very fragmented (to the extent that an attribute list is 
needed to describe it), there is only one portion of the attribute value, and the value of 
LowVcn is zero. 

High Vcn 

The highest valid VCN of this portion of the attribute value. 

Run Array Offset 

The offset, in bytes, from the start of the structure to the run array that contains the 
mappings between VCNs and Logical Cluster Numbers (LCNs). 

Compression Unit 

The compression unit for the attribute expressed as the logarithm to the base two of 
the number of clusters in a compression unit. If CompressionUnit is zero, the attribute 
is not compressed. 

Allocated Size 

The size, in bytes, of disk space allocated to hold the attribute value. 

DataSize 

The size, in bytes, of the attribute value. This may be larger than the AllocatedSize if 
the attribute value is compressed or sparse. 

Initialized Size 

The size, in bytes, of the initialized portion of the attribute value. 

CompressedSize 

The size, in bytes, of the attribute value after compression. This member is only present 
when the attribute is compressed. 

Remarks 

None. 



AttributeStandardlnformation 



typedef struct { 

ULONGLONG CreationTime ; 

ULONGLONG ChangeTime; 

ULONGLONG LastWriteTime; 

ULONGLONG LastAccessTime ; 

ULONG FileAttributes; 

ULONG Alignment0rReserved0rUnknown[3] ; 

ULONG Quotald; // NTFS 3.0 

ULONG Securityld; // NTFS 3.0 

ULONGLONG QuotaCharge; // NTFS 3.0 

USN Usn; // NTFS 3.0 

} STANDARD_INFORMATION , *PSTANDARD_INFORMATION; 



only 

only 

only 

only 
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Members 

CreationTime 

The time when the file was created in the standard time format (that is, the number of 
100-nanosecond intervals since January 1, 1601). 

ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). 

LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). 



FileAttributes 

The attributes of the file. Defined attributes include: 

FILE_ATTRIBUTE_READONLY 

FILE_ATTRIBUTE_HIDDEN 

FI LE_ATTR I BUTE_SYSTEM 

FI LE_ATTR I BUTE_DI RECTORY 

FILE_ATTRIBUTE_ARCHIVE 

FILE_ATTRIBUTE_NORMAL 

FI LE_ATTR I BUTE_TEMPORARY 

F I L E_ATTR I BUT E_S P AR S E_F I L E 

FILE_ATTRIBUTE_REPARSE_POINT 

FILE_ATTRIBUTE_COMPRESSED 

FILE_ATTRIBUTE_OFFLINE 

FI LE_ATTR I BUTE_N0T_C0NTENT_I NDEXED 

FILE_ATTRIBUTE_ENCRYPTED 



Alignment OrReservedOrUnknown 

Normally contains zero. Interpretation unknown. 

Quotald 

A numeric identifier of the disk quota that has been charged for the file (probably an 
index into the file “\$Extend\$Quota”). If quotas are disabled, the value of Quotald is 
zero. This member is only present in NTFS 3.0. If a volume has been upgraded from 
an earlier version of NTFS to version 3.0, this member is only present if the file has 
been accessed since the upgrade. 



Security Id 

A numeric identifier of the security descriptor that applies to the file (probably an 
index into the file “\$Secure”).This member is only present in NTFS 3.0. If a volume 
has been upgraded from an earlier version of NTFS to version 3.0, this member is 
only present if the file has been accessed since the upgrade. 
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QuotaCharge 

The size, in bytes, of the charge to the quota for the file. If quotas are disabled, the 
value of QuotaCharge is zero. This member is only present in NTFS 3.0. If a volume 
has been upgraded from an earlier version of NTFS to version 3.0, this member is 
only present if the file has been accessed since the upgrade. 

Usn 

The Update Sequence Number of the file. If journaling is not enabled, the value of 
Usn is zero. This member is only present in NTFS 3.0. If a volume has been upgraded 
from an earlier version of NTFS to version 3.0, this member is only present if the file 
has been accessed since the upgrade. 

Remarks 

The standard information attribute is always resident. 



AttributeAttributeList 



typedef struct { 

ATTRIBUTE_TYPE AttributeType; 

USHORT Length; 

UCHAR NameLength; 

UCHAR NameOffset; 

UL0NGL0NG LowVcn; 

UL0NGL0NG FileRef erenceNumber ; 

USHORT AttributeNumber; 

USHORT Alignment0rReserved[3] ; 

} ATTRIBUTE_LIST, *PATTRIBUTE_LIST ; 

Members 

AttributeType 

The type of the attribute. 

Length 

The size, in bytes, of the attribute list entry. 

NameLength 

The size, in characters, of the name (if any) of the attribute. 

NameOffset 

The offset, in bytes, from the start of the ATTRIBUTE_LIST structure to the attribute 
name. The attribute name is stored as a Unicode string. 

LowVcn 

The lowest valid Virtual Cluster Number (VCN) of this portion of the attribute value. 

FileReferenceNumber 

The file reference number of the MFT entry containing the NONRESIDENT_ATTRIBUTE 
structure for this portion of the attribute value. 
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AttributeNumber 

A numeric identifier for the instance of the attribute. 

Remarks 

The attribute list attribute is always nonresident and consists of an array of 
ATTRIBUTE_LIST structures. 

An attribute list attribute is only needed when the attributes of a file do not fit in a 
single MFT record. Possible reasons for overflowing a single MFT entry include: 

■ The file has a large numbers of alternate names (hard links) 

■ The attribute value is large, and the volume is badly fragmented 

■ The file has a complex security descriptor (does not affect NTFS 3.0) 

■ The file has many streams 



AttributeFileN ame 



typedef struct { 

UL0NGL0NG DirectoryFileRef erenceNumber ; 



ULONGLONG CreationTime ; // 

UL0NGL0NG ChangeTime; // 

ULONGLONG LastWriteTime ; // 

ULONGLONG LastAccessTime ; // 

ULONGLONG AllocatedSize; // 

ULONGLONG DataSize; // 

ULONG FileAttributes; // 

ULONG AlignmentOrReserved; 

UCHAR NameLength; 

UCHAR NameType; // 0x01 = Long, 0x02 = Short 

WCHAR Name [ 1 ] ; 

} FILENAME_ATTRIBUTE, *PFILENAME_ATTRIBUTE; 



Saved when filename last changed 

ditto 

ditto 

ditto 

ditto 

ditto 

ditto 



Members 



DirectoryFileRef erenceNumber 

The file reference number of the directory in which the filename is entered. 

CreationTime 

The time when the file was created in the standard time format (that is. the number of 
100-nanosecond intervals since January 1, 1601). This member is only updated when 
the filename changes and may differ from the field of the same name in the STAN - 
DARD_INF0RMATI0N structure. 



ChangeTime 

The time when the file attributes were last changed in the standard time format (that 
is, the number of 100-nanosecond intervals since January 1, 1601). This member is 
only updated when the filename changes and may differ from the field of the same 
name in the STANDARD_INFORMATION structure. 
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LastWriteTime 

The time when the file was last written in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). This member is only updated 
when the filename changes and may differ from the field of the same name in the 
STANDARD_INFORMATION structure. 

Last Access Time 

The time when the file was last accessed in the standard time format (that is, the num- 
ber of 100-nanosecond intervals since January 1, 1601). This member is only updated 
when the filename changes and may differ from the field of the same name in the 
STANDARD_INFORMATION structure. 

AllocatedSize 

The size, in bytes, of disk space allocated to hold the attribute value. This member is 
only updated when the filename changes. 

Data Size 

The size, in bytes, of the attribute value. This member is only updated when the file- 
name changes. 



FileAttributes 

The attributes of the file. This member is only updated when the filename changes and 
may differ from the field of the same name in the STANDARD_INFORMATION structure. 

NameLength 

The size, in characters, of the filename. 

NameType 

The type of the name. A type of zero indicates an ordinary name, a type of one indi- 
cates a long name corresponding to a short name, and a type of two indicates a short 
name corresponding to a long name. 

Name 

The name, in Unicode, of the file. 

Remarks 

The filename attribute is always resident. 



AttributeObjectld 



typedef struct { 

GUID Objectld; 
union { 

struct { 

GUID BirthVolumeld; 

GUID BirthObjectld; 

GUID Domainld; 

} ; 

UCHAR ExtendedInfo[48] ; 

}; 

} OBJECTID_ATTRIBUTE , *POBJECTID_ATTRIBUTE ; 
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Members 

Objectld 

The unique identifier assigned to the file. 

BirtVolumeld 

The unique identifier of the volume on which the file was first created. Need not be 
present. 

Birth Objectld 

The unique identifier assigned to the file when it was first created. Need not be 
present. 

Domainld 

Reserved. Need not be present. 

Remarks 

The object identifier attribute is always resident. 



AttributeSecurityDescriptor 



The security descriptor attribute is stored on disk as a standard self-relative security 
descriptor. This attribute does not normally appear in MFT entries on NTFS 3.0 for- 
mat volumes. 



AttributeVolumeN ame 



The volume name attribute just contains the volume label as a Unicode string. 



AttributeVolumelnformation 



typedef struct { 

ULONG Unknown[2] ; 

UCHAR MajorVersion; 

UCHAR MinorVersion; 

USHORT Flags; 

} V0LUME_INF0RMATI0N , *PV0LUME_INF0RMATI0N ; 

Members 

Unknown 

Interpretation unknown. 

MajorVersion 

The major version number of the NTFS format. 

MinorVersion 

The minor version number of the NTFS format. 
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Flags 

A bit array of flags specifying properties of the volume. The values defined include: 
VolumelsDirty 0x0001 



Remarks 

Windows 2000 formats new volumes as NTFS version 3.0. Windows NT 4.0 formats 
new volumes as NTFS version 2.1. 



AttributeD ata 



The data attribute contains whatever data the creator of the attribute chooses. 



AttributelndexRoot 



typedef struct { 

ATTRIBUTE_TYPE Type; 

UL0NG CollationRule; 

UL0NG BytesPerlndexBlock; 

UL0NG ClustersPerlndexBlock; 

DIRECT0RY_INDEX Directorylndex ; 

} INDEX_R00T , *PINDEX_R00T; 

Members 

Type 

The type of the attribute that is indexed. 

CollationRule 

A numeric identifier of the collation rule used to sort the index entries. 

BytesPerlndexBlock 

The number of bytes per index block. 

ClustersPerlndexBlock 

The number of clusters per index block. 

Directorylndex 

A DIRECTORY_INDEX structure. 

Remarks 

An INDEX_R00T structure is followed by a sequence of DIRECT0RY_ENTRY structures. 
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AttributelndexAllocation 



typedef struct { 

NTFS_RECORD_HEADER Ntfs; 

ULONGLONG IndexBlockVcn; 

DIRECTORY_INDEX Directorylndex; 

} INDEX_BLOCK_HEADER, *PINDEX_BLOCK_HEADER ; 

Members 

Ntfs 

An NTFS_RECORD_HEADER structure with a Type of‘lNDX\ 

IndexBlockVcn 

The VCN of the index block. 

Directorylndex 

A DIRECTORY_INDEX structure. 

Remarks 

The index allocation attribute is an array of index blocks. Each index block starts with 
an INDEX_BLOCK_HEADER structure, which is followed by a sequence of DIRECTORY_ENTRY 
structures. 



DIRECTORYJNDEX 



typedef struct { 

ULONG EntriesOff set ; 

ULONG IndexBlockLength; 

ULONG AllocatedSize; 

ULONG Flags; // 0x00 = Small directory, 0x01 = Large directory 

} DIRECTORY_INDEX, *PDIRECTORY_INDEX; 

Members 

EntriesOffset 

The offset, in bytes, from the start of the structure to the first DIRECTORY_ENTRY 
structure. 

IndexBlockLength 

The size, in bytes, of the portion of the index block that is in use. 

AllocatedSize 

The size, in bytes, of disk space allocated for the index block. 
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Flags 

A bit array of flags specifying properties of the index. The values defined include: 

SmallDirectory 0x0000 // Directory fits in index root 

LargeDirectory 0x0001 // Directory overflows index root 



Remarks 

None. 



DIRECTORY_ENTRY 



typedef struct { 

UL0NGL0NG FileRef erenceNumber ; 

USHORT Length; 

USHORT AttributeLength; 

ULONG Flags; // 0x01 = Has trailing VCN, 0x02 = Last entry 

// F I LENAME_ATTR I BUTE Name; 

// ULONGLONG Vcn; // VCN in IndexAllocation of earlier entries 

} DIRECTORY_ENTRY, *PDIRECTORY_ENTRY ; 

Members 

FileReferenceNumber 

The file reference number of the file described by the directory entry. 

Length 

The size, in bytes, of the directory entry. 

AttributeLength 

The size, in bytes, of the attribute that is indexed. 



A bit array of flags specifying properties of the entry. The values defined include: 

HasTrailingVcn 0x0001 // A VCN follows the indexed attribute 

LastEntry 0x0002 // The last entry in an index block 



Remarks 

Until NTFS version 3.0, only filename attributes were indexed. 

If the HasTrailingVcn flag of a DIRECTORYJENTRY structure is set, the last eight bytes of 
the directory entry contain the VCN of the index block that holds the entries imme- 
diately preceding the current entry. 



AttributeBitmap 



The bitmap attribute contains an array of bits. The file “\$Mft” contains a bitmap 
attribute that records which MFT table entries are in use, and directories normally 
contain a bitmap attribute that records which index blocks contain valid entries. 
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AttributeReparsePoint 



typedef struct { 

ULONG ReparseTag; 

USHORT ReparseDataLength; 

USHORT Reserved; 

UCHAR ReparseData[ 1 ] ; 

} REPARSE_POINT, *PREPARSE_POINT; 

Members 

ReparseTag 

The reparse tag identifies the type of reparse point. The high order three bits of the tag 
indicate whether the tag is owned by Microsoft, whether there is a high latency in 
accessing the file data, and whether the filename is an alias for another object. 

ReparseDataLength 

The size, in bytes, of the reparse data in the ReparseData member. 

ReparseData 

The reparse data. The interpretation of the data depends upon the type of the reparse 
point. 



Remarks 

None. 



AttributeEAlnformation 



typedef struct { 

ULONG EaLength; 

ULONG EaQueryLength; 

} EA_INF0RMATI0N , *PEA_INFORMATION ; 

Members 

EaLength 

The size, in bytes, of the extended attribute information. 

Ea Query Length 

The size, in bytes, of the buffer needed to query the extended attributes when calling 

ZwQueryEaFile. 

Remarks 

None. 
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AttributeEA 



typedef struct { 

ULONG NextEntryOff set ; 

UCHAR Flags; 

UCHAR EaNameLength; 

USHORT EaValueLength; 

CHAR EaName[1 ] ; 

// UCHAR EaDataM; 

} EA_ATTRIBUTE, *PEA_ATTRIBUTE ; 

Members 

NextEntry Offset 

The number of bytes that must be skipped to get to the next entry. 

Flags 

A bit array of flags qualifying the extended attribute. 

EaNameLength 

The size, in bytes, of the extended attribute name. 

Ea ValueLength 

The size, in bytes, of the extended attribute value. 

EaName 

The extended attribute name. 

EaData 

The extended attribute data. 



Remarks 

None. 



AttributePropertySet 



Intended to support Native Structured Storage (NSS) — a feature that was removed 
from NTFS 3.0 during beta testing. 



AttributeLoggedUtilityStream 



A logged utility stream attribute contains whatever data the creator of the attribute 
chooses, but operations on the attribute are logged to the NTFS log file just like 
NTFS metadata changes. It is used by the Encrypting File System (EFS). 
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Special Files 



The first sixteen entries in the Master File Table (MFT) are reserved for special files. 
NTFS 3.0 uses only the first twelve entries. 

\$MFT (entry 0) 

The Master File Table. The data attribute contains the MFT entries, and the bitmap 
attribute records which entries are in use. 

\$MFTMirr (entry 1) 

A mirror (backup copy) of the first four entries of the MFT. 

\$LogFile (entry 2) 

The volume log file that records changes to the volume structure. 

\$Volume (entry 3) 

The data attribute of $Volume represents the whole volume. Opening the Win32 path- 
name “\\ . \ C:” opens the volume file on drive C: (presuming that C: is an NTFS- 
formatted volume). 

The $Volume file also has volume name, volume information, and object identifier 
attributes. 



\$AttrDef (entry 4) 

The data attribute of $AttrDef contains an array of attribute definitions. 

typedef struct { 

WCHAR AttributeName[64] ; 

ULONG AttributeNumber; 

ULONG Unknown[2] ; 

ULONG Flags; 

UL0NGL0NG MinimumSize; 

UL0NGL0NG MaximumSize; 

} ATTRIBUTE_DEFINITION , *PATTRIBUTE_DEFINITION ; 

\ (entry 5) 

The root directory of the volume. 



\$Bitmap (entry 6) 

The data attribute of $Bitmap is a bitmap of the allocated clusters on the volume. 



\$Boot (entry 7) 

The first sector of $Boot is also the first sector of the volume. Because it is used early 
in the system boot process (if the volume is bootable), space is at a premium and the 
data stored in it is not aligned on natural boundaries. The format of the first sector can 
be represented by a B00T_BL0CK structure. 

#pragma pack(push, 1) 

typedef struct { 

UCHAR Jump[3] ; 
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UCHAR Format [8]; 

USHORT BytesPerSector; 

UCHAR SectorsPerCluster; 
USHORT BootSectors; 

UCHAR Mbzl; 

USHORT Mbz2; 

USHORT Reservedl ; 

UCHAR MediaType; 

USHORT Mbz3; 

USHORT SectorsPerTrack; 

USHORT NumberOf Heads; 

ULONG PartitionOff set ; 

ULONG Reserved2[2] ; 

ULONGLONG TotalSectors ; 
ULONGLONG MftStartLcn; 
ULONGLONG Mft2StartLcn ; 

ULONG ClustersPerFileRecord; 
ULONG ClustersPerlndexBlock; 
ULONGLONG VolumeSerialNumber ; 
UCHAR Code [ 0x1 AE]; 

USHORT BootSignature; 

} BOOT_BLOCK, *PBOOT_BLOCK; 

#pragma pack(pop) 



\$BadClus (entry 8) 

Bad clusters are appended to the data attribute of this file. 



\$Secure (entry 9) 

The data attribute of $Secure contains the shared security descriptors. $Secure also has 
two indexes. 



\$UpCase (entry 10) 

The data attribute of $Upcase contains the uppercase equivalent of all 65536 Unicode 
characters. 



\$Extend (entry 11) 

$Extend is a directory that holds the special files used by some of the extended func- 
tionality of NTFS 3.0. The (semi-) special files which are stored in the directory 
include “$0bj Id,” “$Quota,” “$Reparse” and “$UsnJrnl.” 



Opening Special Files 



Although the special files are indeed files, they cannot normally be opened by calling 
ZwOpenFile or ZwCreateFile because even though the ACL on the special files grants 
read access to Administrators, ntfs.sys (the NTFS file system driver) always returns 
STATUS_ACCESS_DENIED. There are two variables in ntfs.sys that affect this behavior: 

Ntf sProtectSystemFiles and Ntf sProtectSystemAttributes. By default, both of these 
variables are set to TRUE. 

If Ntf sProtectSystemAttributes is set to FALSE (by a debugger, for example), the sys- 
tem attributes (such as the standard information attribute) can be opened, using the 
names of the form “filename: : $STANDARD_INF0RMATI0N.” 
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If Ntf sProtectSystemFiles is set to FALSE, then the special files can be opened. There 
are, however, some drawbacks associated with attempting to do this: Because many of 
the special files are opened in a special way when mounting the volume, they are not 
prepared to handle the IRP_MJ_READ requests resulting from a call to ZwReadFile, and 
the system crashes if such a request is received. These special files can be read by map- 
ping the special file with ZwCreateSection and ZwMapViewOfSection and then reading 
the mapped data. A further problem is that a few of the special files are not prepared to 
handle the IRP_MJ_CLEANUP request that is generated when the last handle to a file 
object is closed, and the system crashes if such a request is received. The only option is 
to duplicate the open handle to the special file into a process that never terminates 
(such as the system process). 



Recovering Data from Deleted Files 



Example E.l demonstrates how to recover data from the unnamed data attribute of a 
file identified by drive letter and MFT entry index — even if the MFT entry represents 
a deleted file. It can also display a list of the deleted files on the volume. MFT entries 
are allocated on a first-free basis, so the entries for deleted files are normally quickly 
reused. Therefore, the example is of little practical use for recovering deleted files, but 
it can be used to make copies of the unnamed data attributes of the special files. 

If the file to be recovered is compressed, the recovered data remains compressed and 
can be decompressed by a separate utility; Example E.2 shows one way in which 
this can be done. 



Example E.l: Recovering Data from a File 



#include <windows.h> 

#include <stdlib.h> 

#include <stdio.h> 

#include "ntfs.h" 

ULONG BytesPerFileRecord; 

HANDLE hVolume; 

B00T_BL0CK bootb; 

PFILE_RECORD_HEADER MFT; 

template <class T1 , class T2> inline 

T1 * Padd(T1* p, T2 n) { return (T1*)((char *)p + n); } 

ULONG RunLength(PUCHAR run) 

{ 

return (*run & 0xf) + ((*run » 4) & 0xf) + 1; 

} 

LONGLONG RunLCN (PUCHAR run) 

{ 

UCHAR nl = *run & 0xf; 

UCHAR n2 = (*run » 4) & 0xf; 

LONGLONG lcn = n2 == 0 ? 0 : CHAR ( run [nl + n2] ) ; 

for (LONG i = nl + n2 - 1; i > nl ; i-) 
lcn = (lcn « 8) + run[i]; 
return lcn; 



} 
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ULONGLONG RunCount ( PUCHAR run) 

{ 

UCHAR n = *run & 0xf; 
ULONGLONG count = 0; 



for (ULONG i = n; i > 0; i— ) 

count = (count « 8) + run[i]; 
return count; 



BOOL FindRun (PNONRESIDENT_ATTRIBUTE attr, ULONGLONG vcn, 
PULONGLONG lcn, PULONGLONG count) 



{ 

if (vcn < attr->LowVcn J | vcn > attr->HighVcn) return FALSE; 



*lcn = 0; 

ULONGLONG base = attr->LowVcn; 



for (PUCHAR run = PUCHAR(Padd(attr, attr->RunArrayOff set) ) ; 
*run ! = 0; 

run += RunLength(run) ) { 

*lcn += RunLCN(run) ; 

*count = RunCount (run) ; 

if (base <= vcn && vcn < base + *count) { 

*lcn = RunLCN(run) == 0 ? 0 : *lcn + vcn - base; 
*count -= UL0NG(vcn - base); 

return TRUE; 

} 

else 

base += *count; 



return FALSE; 



PATTRIBUTE FindAttribute (PFILE_RECORD_HEADER file, 

ATTR I BUTE_TYPE type, PWSTR name) 



{ 



for (PATTRIBUTE attr = PATTRIBUTE (Padd (file, f ile->AttributesOff set ) ) ; 
attr->AttributeType != -1; 
attr = Padd(attr, attr->Length) ) { 



if (attr->AttributeType == type) { 

if (name == 0 && attr->NameLength == 0) return attr; 

if (name != 0 && wcslen(name) == attr->NameLength 

&& _wcsicmp(name, PWSTR (Padd (attr, attr->NameOffset ) ) ) == 0) 
return attr; 

} 

} 

return 0; 

} 



VOID FixupUpdateSequenceArray (PFILE_RECORD_HEADER file) 

{ 

PUSHORT usa = PUSHORT(Padd(file, file->Ntfs.UsaOffset) ) ; 
PUSHORT sector = PUSHORT(f ile) ; 
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for (UL0N6 i = 1; i < f ile ->Ntf s . UsaCount ; i++) { 
sector[255] = usa[i] ; 
sector += 256; 

} 

} 

VOID ReadSector(ULONGLONG sector, ULONG count, PVOID buffer) 

{ 

ULARGE_INTEGER offset; 

OVERLAPPED overlap = {0}; 

ULONG n; 

off set .QuadPart = sector * bootb.BytesPerSector; 

overlap. Off set = offset .LowPart; overlap. Off setHigh = offset .HighPart; 
ReadFile(hVolume, buffer, count * bootb.BytesPerSector, &n, &overlap); 

} 



VOID ReadLCN(ULONGLONG lcn, ULONG count, PVOID buffer) 

{ 

ReadSector(lcn * booth. SectorsPerCluster, 

count * bootb. SectorsPerCluster, buffer); 



} 



VOID ReadExternalAttribute(PNONRESIDENT_ATTRIBUTE attr, 

ULONGLONG vcn, ULONG count, PVOID buffer) 

{ 

ULONGLONG lcn, runcount; 

ULONG readcount, left; 

PUCHAR bytes = PUCHAR(buffer) ; 

for (left = count; left > 0; left -= readcount) { 

FindRun(attr, vcn, &lcn, &runcount); 

readcount = UL0NG(min( runcount, left)); 

ULONG n = readcount * bootb.BytesPerSector * bootb. SectorsPerCluster; 

if (lcn == 0) 

memset (bytes, 0, n); 

else 

ReadLCN(lcn, readcount, bytes); 

vcn += readcount; 
bytes += n; 

} 

} 

ULONG AttributeLength(PATTRIBUTE attr) 

{ 

return attr->Nonresident == FALSE 

? PRESIDENT_ATTRIBUTE(attr) ->ValueLength 
: ULONG ( PNONRESIDENT_ATTRIBUTE ( att r ) ->DataSize) ; 



ULONG AttributeLengthAllocated(PATTRIBUTE attr) 

{ 

return attr->Nonresident == FALSE 

? PRESIDENT_ATTRIBUTE(attr) ->ValueLength 
: ULONG ( PNONRESIDENT_ATTRIBUTE ( att r ) ->AllocatedSize) ; 

} 
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VOID ReadAtt ribute ( PATTRIBUTE attr, PVOID buffer) 

{ 

if (attr->Nonresident == FALSE) { 

PRESIDENT_ATTRIBUTE rattr = PRESIDENT_ATTRIBUTE(attr) ; 

memcpy (buffer, Padd(rattr, rattr->ValueOff set) , rattr->ValueLength) ; 

} 

else { 

PNONRESIDENT_ATTRIBUTE nattr = PNONRESIDENT_ATTRIBUTE(attr) ; 
ReadExternalAttribute(nattr, 0, ULONG(nattr->HighVcn) + 1, buffer); 

} 

} 



VOID ReadVCN(PFILE_RECORD_HEADER file, ATTRIBUTE_TYPE type, 
ULONGLONG vcn, ULONG count, PVOID buffer) 



{ 



PNONRESIDENT_ATTRIBUTE attr 

= PNONRESIDENT_ATTRIBUTE(FindAtt ribute (file, type, 0)); 

if (attr == 0 | | (vcn < attr->LowVcn |j vcn > attr->HighVcn) ) { 

// Support for huge files 

PATTRIBUTE attrlist = FindAttribute(f ile, AttributeAttributeList , 0); 
DebugBreak( ) ; 



ReadExternalAttribute(attr, vcn, count, buffer); 

} 

VOID ReadFileRecord (ULONG index, PFILE_RECORD_HEADER file) 

{ 

ULONG clusters = bootb.ClustersPerFileRecord; 
if (clusters > 0x80) clusters = 1; 

PUCHAR p = new UCHAR[ booth. BytesPerSector 

* bootb.SectorsPerCluster * clusters]; 

ULONGLONG vcn = ULONGLONG(index) * BytesPerFileRecord 

/ bootb.BytesPerSector / bootb.SectorsPerCluster; 

ReadVCN(MFT, AttributeData, vcn, clusters, p); 

LONG m = (bootb.SectorsPerCluster * bootb.BytesPerSector 
/ BytesPerFileRecord) - 1; 

ULONG n = m > 0 ? (index & m) : 0; 

memcpy (file, p + n * BytesPerFileRecord, BytesPerFileRecord) ; 
delete [] p; 

FixupUpdateSequenceArray (f ile) ; 

} 



VOID LoadMFT ( ) 

{ 

BytesPerFileRecord = bootb.ClustersPerFileRecord < 0x80 
? bootb.ClustersPerFileRecord 

* bootb.SectorsPerCluster 

* bootb.BytesPerSector 

: 1 « (0x100 - bootb.ClustersPerFileRecord) ; 



NTFS On-Disk Structure: Example E.1 



479 



1996 AppE 12/1/99 



12:33 PM Page 479 



MFT = PFI LE_RECORD_HEADER ( new UCHAR [ BytesPerFileRecord ] ) ; 

ReadSector (bootb.MftStartL.cn * bootb.SectorsPerCluster, 

BytesPerFileRecord / bootb.BytesPerSector, MFT); 

FixupUpdateSequenceArray (MFT) ; 

} 

BOOL bitset (PUCHAR bitmap, ULONG i) 

{ 

return (bitmap[i » 3] & (1 « (i & 7))) != 0; 

} 

VOID FindDeleted() 

{ 

PATTRIBUTE attr = FindAttribute (MFT, AttributeBitmap, 0); 

PUCHAR bitmap = new UCHAR[AttributeLengthAllocated(attr) ] ; 

ReadAttribute(attr, bitmap); 

ULONG n = AttributeLength(FindAttribute(MFT, AttributeData, 0)) 

/ BytesPerFileRecord; 

PFILE_RECORD_HEADER file 

= PFILE_RECORD_HEADER(new UCHAR[BytesPerFileRecord] ) ; 

for (ULONG i = 0; i < n; i++) { 

if (bitset (bitmap, i)) continue; 

ReadFileRecord(i, file); 

if (f ile->Ntf s .Type == ' ELIF 1 && (file->Flags & 1) == 0) { 
attr = FindAttribute(file, AttributeFileName, 0); 
if (attr == 0) continue; 

PFILENAME_ATTRIBUTE name 

= PFILENAME_ATTRIBUTE(Padd (attr , 

PRESIDENT_ATTRIBUTE(attr) ->ValueOff set ) ) ; 

printf ( "%81u %. *ws\n" , i, int (name->NameLength) , name->Name); 

} 

} 

} 

VOID DumpData(ULONG index, PCSTR filename) 

{ 

PFILE_RECORD_HEADER file 

= PFILE_RECORD_HEADER(new UCHAR[BytesPerFileRecord] ) ; 

ULONG n; 

ReadFileRecord(index, file); 

if (file->Ntfs.Type != 'ELIF') return; 

PATTRIBUTE attr = FindAttribute (file , AttributeData, 0); 
if (attr == 0) return; 

PUCHAR buf = new UCHAR[AttributeLengthAllocated(attr) ] ; 
ReadAttribute(attr, buf); 

HANDLE hFile = CreateFile (filename , GENERICJVRITE, 0, 0, 

CREATE_ALWAYS, 0, 0); 
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WriteFile(hFile, buf, AttributeLength(attr) , &n, 0); 
CloseHandle(hFile) ; 
delete [] buf; 

} 

int main(int argc, char *argv[]) 

{ 

CHAR drive [] = " \\\\ . \\C: " ; 

ULONG n; 

if (argc < 2) return 0; 

drive[4] = argv[ 1 ] [0] ; 

hVolume = CreateFile(drive, GENERIC_READ, 

FILE_SHARE_READ j FILE_SHARE_WRITE, 0, 
OPEN_EXISTING, 0, 0); 

ReadFile( hVolume, &bootb, sizeof bootb, &n, 0); 

LoadMFT ( ) ; 

if (argc == 2) FindDeleted( ) ; 

if (argc == 4) DumpData(strtoul(argv[2] , 0, 0), arg v [ 3 ] ) ; 
CloseHandle (hVolume) ; 
return 0; 

} 



Example E.2: Decompressing Recovered Data 



#include <windows.h> 

typedef ULONG NTSTATUS; 

extern "C" 

NTSTATUS 

NTAPI 

RtlDecompressBuffer( 

USHORT CompressionFormat , 
PVOID OutputBuffer, 

ULONG OutputBufferLength, 
PVOID InputBuffer, 

ULONG InputBufferLength, 
PULONG ReturnLength 
); 



int main(int argc, char *argv[]) 

{ 

if (argc != 3) return 0; 

HANDLE hFilel = CreateFile(argv[ 1 ] , GENERIC_READ, 

FI LE_SHARE_READ , 0, OPEN_EXISTING, 0, 0); 
HANDLE hFile2 = CreateFile(argv[2] , GENERIC_READ | GENERIC_WRITE, 

FI LE_SHARE_READ , 0, CREATE_ALWAYS, 0, 0); 
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ULONG n = GetFileSize(hFile1 , 0); 

HANDLE hMappingl = CreateFileMapping(hFile1 , 0, PAGE_READONLY, 0, 0, 0); 
HANDLE hMapping2 = CreateFileMapping(hFile2, 0, PAG E_R E ADWR I T E , 0, n, 0); 

PCHAR p = PCHAR ( MapViewOf FileEx ( hMappingl , FILE_MAP_READ, 0, 0, 0, 0)); 
PCHAR q = PCHAR ( MapViewOf FileEx ( hMapping2 , FILE_MAP_WRITE, 0, 0, 0, 0)); 

for (ULONG m, i = 0; i < n; i += m) 

RtlDecompressBuff er (COMPRESSION_FORMAT_LZNT1 , 

q+i, n - i, p+i, n - i, &m); 



return 0; 

} 
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